Add criteria checklist

- add pr validation checklist

.github/CONTRIBUTOR_ACCEPTANCE_CHECKLIST.md

@@ -0,0 +1,36 @@
+# External Contributor Acceptance Checklist
+
+This document outlines the requirements that all external contributors must complete before submitting a pull request to the Nym repository. Following this checklist ensures code quality, maintainability, and alignment with project standards.
+
+## Code Quality and Compilation
+
+All contributions must compile successfully without warnings or errors across the supported platforms. Before submitting your pull request, verify that your code compiles cleanly using `cargo build --workspace --all-targets`. The codebase uses the latest Rust version in most placesas specified in the workspace Cargo.toml, and your contribution must be compatible with this requirement. All code must pass `cargo clippy --workspace --all-targets -- -D warnings` without any clippy warnings or lints. This means zero tolerance for clippy suggestions, unused imports, dead code, or any other code quality issues that clippy would flag. Additionally, all code must be properly formatted using `cargo fmt --all`, and the CI pipeline will reject any pull request that fails the formatting check.
+
+## Testing Requirements
+
+Every contribution must include appropriate test coverage for the functionality being added or modified. For new features, include unit tests that verify the core behavior and edge cases. For bug fixes, include regression tests that prevent the issue from reoccurring. All existing tests must continue to pass, and you must run `cargo test --workspace` locally to verify this before submission. Integration tests should be included when the contribution affects interactions between multiple components or systems. Test coverage should demonstrate that the code behaves correctly under both normal and error conditions, and any error handling paths should be explicitly tested.
+
+## Documentation and Evidence
+
+For user-facing features or significant changes, provide clear documentation of the functionality. This includes code comments explaining complex logic, updated README files if the contribution affects setup or usage instructions, and inline documentation for public APIs. When the contribution involves UI changes, user flows, or visual modifications, include screenshots or screen recordings that demonstrate the feature working as intended. These visual artifacts should show the complete user journey, including any error states or edge cases that users might encounter. For backend or infrastructure changes, provide diagrams or written descriptions of the architecture changes and how they integrate with existing systems.
+
+## Component Impact Analysis
+
+Clearly document which components, modules, or subsystems your contribution touches. This includes listing all files modified, added, or removed, and explaining the scope of changes within each file. Describe how your changes interact with existing code, including any dependencies you've added or modified, and explain why these dependencies are necessary. If your contribution affects multiple areas of the codebase, provide a clear explanation of how these changes work together and why they were implemented as a cohesive unit rather than separate contributions.
+
+## Functional Benefits and Justification
+
+Articulate the specific benefits your contribution provides to the project. Explain what problem it solves, who benefits from the change, and how it improves the user experience or system functionality. If the contribution addresses a specific issue or feature request, reference the relevant issue number and explain how your implementation fulfills the requirements. For performance improvements, include benchmarks or metrics that demonstrate the enhancement. For new features, explain the use case and how it fits into the broader project goals. If the contribution refactors existing code, explain why the refactoring was necessary and what improvements it brings in terms of maintainability, readability, or performance.
+
+## Workflow Compliance
+
+Your contribution must align with all project workflows and CI/CD requirements. This means your code must pass all automated checks in the GitHub Actions workflows, including build verification, linting, formatting, and test execution. The CI pipeline runs `cargo clippy` with `-D warnings` on all platforms, and any warnings will cause the build to fail. Ensure that your local development environment matches the CI environment as closely as possible, and run the same commands locally that the CI pipeline executes. If your contribution affects areas covered by specialized workflows such as contract compilation, WASM builds, or platform-specific builds, verify that those workflows also pass successfully.
+
+## Code Review Readiness
+
+Before marking your pull request as ready for review, ensure that all items in this checklist are complete. Your pull request description should reference this checklist and confirm that each requirement has been met. Include links to any external documentation, screenshots, or test results that support your contribution. Be prepared to answer questions about design decisions, implementation choices, and alternative approaches that were considered. The code should be self-explanatory where possible, with clear variable names, function names, and structure that make the intent obvious to reviewers who may not be familiar with the specific area of the codebase you've modified.
+
+## Acceptance Criteria Summary
+
+In summary, your contribution is ready for review when it compiles without warnings, passes all clippy checks with zero tolerance for warnings, includes comprehensive tests, provides clear documentation and visual evidence where applicable, clearly explains component impacts and functional benefits, complies with all workflow requirements, and is presented in a manner that facilitates efficient code review. Meeting these standards ensures that external contributions maintain the high quality bar expected in the Nym codebase and reduces the review burden on maintainers while preventing issues from reaching production.
+

.github/workflows/ci-build-vpn-api-wasm.yml

@@ -37,6 +37,18 @@ jobs:
       - name: Install wasm-bindgen-cli
         run: cargo install wasm-bindgen-cli
 
+      - name: Check formatting
+        uses: actions-rs/cargo@v1
+        with:
+          command: fmt
+          args: --manifest-path nym-credential-proxy/vpn-api-lib-wasm/Cargo.toml --all -- --check
+
+      - name: Run clippy
+        uses: actions-rs/cargo@v1
+        with:
+          command: clippy
+          args: --manifest-path nym-credential-proxy/vpn-api-lib-wasm/Cargo.toml --target wasm32-unknown-unknown -- -D warnings
+
       - name: "Build"
         run: make
         working-directory: nym-credential-proxy/vpn-api-lib-wasm

.github/workflows/pr-validation.yml

@@ -27,3 +27,16 @@ jobs:
     steps:
       - if: github.event.pull_request.milestone == null && contains( env.LABELS, 'no-milestone' ) == false
         run: exit 1
+
+  check-contributor-checklist:
+    name: Check Contributor Checklist Reference
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check PR description references checklist
+        run: |
+          PR_BODY="${{ github.event.pull_request.body }}"
+          if [[ -z "$PR_BODY" ]] || [[ ! "$PR_BODY" =~ "CONTRIBUTOR_ACCEPTANCE_CHECKLIST" ]] && [[ ! "$PR_BODY" =~ "contributor.*checklist" ]]; then
+            echo "::warning::PR description should reference .github/CONTRIBUTOR_ACCEPTANCE_CHECKLIST.md for external contributors"
+            echo "Please ensure you have reviewed and completed all items in the contributor acceptance checklist."
+          fi

.github/workflows/push-data-observatory.yaml

@@ -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

.gitignore

@@ -63,3 +63,5 @@ nym-api/redocly/formatted-openapi.json
 
 **/settings.sql
 **/enter_db.sh
+
+*.profraw

Cargo.toml

@@ -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",
@@ -263,9 +266,10 @@ 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"
+hickory-resolver = "0.25.2"
 hkdf = "0.12.3"
 hmac = "0.12.1"
 http = "1"
@@ -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 }

ansible/nym-node/playbooks/ansible.cfg

@@ -0,0 +1,191 @@
+# config file for ansible -- http://ansible.com/
+# ==============================================
+
+# nearly all parameters can be overridden in ansible-playbook 
+# or with command line flags. ansible will read ANSIBLE_CONFIG,
+# ansible.cfg in the current working directory, .ansible.cfg in
+# the home directory or /etc/ansible/ansible.cfg, whichever it
+# finds first
+
+[defaults]
+# some basic default values...
+
+inventory       = inventory/all
+#library        = /usr/share/my_modules/
+remote_tmp     = $HOME/.ansible/tmp
+pattern        = *
+forks          = 5
+poll_interval  = 15
+transport      = smart
+remote_port    = 22
+module_lang    = C
+
+# plays will gather facts by default, which contain information about
+# the remote system.
+#
+# smart - gather by default, but don't regather if already gathered
+# implicit - gather by default, turn off with gather_facts: False
+# explicit - do not gather by default, must say gather_facts: True
+gathering = implicit
+
+# additional paths to search for roles in, colon separated
+roles_path    = ../roles
+
+# uncomment this to disable SSH key host checking
+host_key_checking = False
+
+# what flags to pass to sudo
+#sudo_flags = -H
+
+# SSH timeout
+timeout = 100
+
+# default user to use for playbooks if user is not specified
+# (/usr/bin/ansible will use current user as default)
+#remote_user = root
+
+# logging is off by default unless this path is defined
+# if so defined, consider logrotate
+#log_path = /var/log/ansible.log
+
+# default module name for /usr/bin/ansible
+#module_name = command
+
+# use this shell for commands executed under sudo
+# you may need to change this to bin/bash in rare instances
+# if sudo is constrained
+#executable = /bin/sh
+
+# if inventory variables overlap, does the higher precedence one win
+# or are hash values merged together?  The default is 'replace' but
+# this can also be set to 'merge'.
+#hash_behaviour = replace
+
+# list any Jinja2 extensions to enable here:
+#jinja2_extensions = jinja2.ext.do,jinja2.ext.i18n
+
+# if set, always use this private key file for authentication, same as 
+# if passing --private -key to ansible or ansible-playbook
+#private_key_file = /path/to/file
+
+# format of string {{ ansible_managed }} available within Jinja2 
+# templates indicates to users editing templates files will be replaced.
+# replacing {file}, {host} and {uid} and strftime codes with proper values.
+ansible_managed = Ansible managed: {file} modified on %Y-%m-%d %H:%M:%S by {uid} on {host}
+
+# by default, ansible-playbook will display "Skipping [host]" if it determines a task
+# should not be run on a host.  Set this to "False" if you don't want to see these "Skipping" 
+# messages. NOTE: the task header will still be shown regardless of whether or not the 
+# task is skipped.
+#display_skipped_hosts = True
+
+# by default (as of 1.3), Ansible will raise errors when attempting to dereference 
+# Jinja2 variables that are not set in templates or action lines. Uncomment this line
+# to revert the behavior to pre-1.3.
+#error_on_undefined_vars = False
+
+# by default (as of 1.6), Ansible may display warnings based on the configuration of the
+# system running ansible itself. This may include warnings about 3rd party packages or
+# other conditions that should be resolved if possible.
+# to disable these warnings, set the following value to False:
+#system_warnings = True
+
+# by default (as of 1.4), Ansible may display deprecation warnings for language
+# features that should no longer be used and will be removed in future versions.
+# to disable these warnings, set the following value to False:
+#deprecation_warnings = True
+
+# (as of 1.8), Ansible can optionally warn when usage of the shell and
+# command module appear to be simplified by using a default Ansible module
+# instead.  These warnings can be silenced by adjusting the following
+# setting or adding warn=yes or warn=no to the end of the command line 
+# parameter string.  This will for example suggest using the git module
+# instead of shelling out to the git command.
+# command_warnings = False
+
+
+# set plugin path directories here, separate with colons
+action_plugins     = ../../other/plugins/action
+callback_plugins   = ../../other/plugins/callback
+connection_plugins = ../../other/plugins/connection
+lookup_plugins     = ../../other/plugins/lookup
+vars_plugins       = ../../other/plugins/vars
+filter_plugins     = ../../other/plugins/filter
+
+# by default callbacks are not loaded for /bin/ansible, enable this if you
+# want, for example, a notification or logging callback to also apply to 
+# /bin/ansible runs
+#bin_ansible_callbacks = False
+
+
+# don't like cows?  that's unfortunate.
+# set to 1 if you don't want cowsay support or export ANSIBLE_NOCOWS=1 
+#nocows = 1
+
+# don't like colors either?
+# set to 1 if you don't want colors, or export ANSIBLE_NOCOLOR=1
+#nocolor = 1
+
+# the CA certificate path used for validating SSL certs. This path 
+# should exist on the controlling node, not the target nodes
+# common locations:
+# RHEL/CentOS: /etc/pki/tls/certs/ca-bundle.crt
+# Fedora     : /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem
+# Ubuntu     : /usr/share/ca-certificates/cacert.org/cacert.org.crt
+#ca_file_path = 
+
+# the http user-agent string to use when fetching urls. Some web server
+# operators block the default urllib user agent as it is frequently used
+# by malicious attacks/scripts, so we set it to something unique to 
+# avoid issues.
+#http_user_agent = ansible-agent
+
+# if set to a persistant type (not 'memory', for example 'redis') fact values
+# from previous runs in Ansible will be stored.  This may be useful when
+# wanting to use, for example, IP information from one group of servers
+# without having to talk to them in the same playbook run to get their
+# current IP information.
+fact_caching = memory
+
+[paramiko_connection]
+
+# uncomment this line to cause the paramiko connection plugin to not record new host
+# keys encountered.  Increases performance on new host additions.  Setting works independently of the
+# host key checking setting above.
+#record_host_keys=False
+
+# by default, Ansible requests a pseudo-terminal for commands executed under sudo. Uncomment this
+# line to disable this behaviour.
+#pty=False
+
+[ssh_connection]
+
+# ssh arguments to use
+# Leaving off ControlPersist will result in poor performance, so use 
+# paramiko on older platforms rather than removing it
+#ssh_args = -o ControlMaster=auto -o ControlPersist=60s
+
+# The path to use for the ControlPath sockets. This defaults to
+# "%(directory)s/ansible-ssh-%%h-%%p-%%r", however on some systems with
+# very long hostnames or very long path names (caused by long user names or 
+# deeply nested home directories) this can exceed the character limit on
+# file socket names (108 characters for most platforms). In that case, you 
+# may wish to shorten the string below.
+# 
+# Example: 
+# control_path = %(directory)s/%%h-%%r
+#control_path = %(directory)s/ansible-ssh-%%h-%%p-%%r
+
+# Enabling pipelining reduces the number of SSH operations required to 
+# execute a module on the remote server. This can result in a significant 
+# performance improvement when enabled, however when using "sudo:" you must 
+# first disable 'requiretty' in /etc/sudoers
+#
+# By default, this option is disabled to preserve compatibility with
+# sudoers configurations that have requiretty (the default on many distros).
+# 
+#pipelining = False
+
+# if True, make ansible use scp if the connection type is ssh 
+# (default is sftp)
+scp_if_ssh = True

ansible/nym-node/playbooks/bond.yml

@@ -0,0 +1,8 @@
+---
+- name: Nym node bonding / post-installation
+  hosts: all    # or a specific host/group
+  gather_facts: false
+  serial: 1  
+
+  roles:
+    - role: postinstall

ansible/nym-node/playbooks/deploy.yml

@@ -0,0 +1,10 @@
+---
+- name: "Deploy Nym node"
+  hosts: all    # or a specific host/group
+  become: true
+  roles:
+    - base
+    - nym
+    - nginx
+    - tunnel # comment out for mixnode
+    - quic   # comment out for mixnode or non-wireguard gateway

ansible/nym-node/playbooks/group_vars/all.yml

@@ -0,0 +1,44 @@
+---
+ansible_ssh_private_key_file: ~/.ssh/<SSH_KEY>
+
+# nym_version: "v2025.21-mozzarella"
+# 
+# NOTE:
+# if you want to pin Nym to a specific version instead of using the
+# latest release from GitHub in /tasks/main.yml then
+# uncomment the line above and set the tag
+
+cli_url: "https://github.com/nymtech/nym/releases/download/nym-binaries-{{ nym_version }}/nym-cli"
+tunnel_manager_url: "https://github.com/nymtech/nym/raw/refs/heads/develop/scripts/nym-node-setup/network-tunnel-manager.sh"
+quic_bridge_deployment_url: "https://raw.githubusercontent.com/nymtech/nym/refs/heads/develop/scripts/nym-node-setup/quic_bridge_deployment.sh"
+
+# NOTE: These values will be used globally unless overwritten per node in inventory/all
+ansible_user: root                       # used for ssh, like `ssh root@nym-exit.ch-1.mynodes.net`
+email: "<EMAIL>"                         # used in certbot, description.toml and landing page
+website: "<WEBSITE>"                     # it is used in the description.toml
+description: "<NODE_PUBLIC_DESCRIPTION>" # or define per node in inventory/all
+
+# NOTE: Set these vars if you want them globally for all nodes
+# Per node changes in inventory/all will overwrite these global ones:
+hostname: ""            # this is a fallback, keep it and setup hostname per node in inventory/all
+# moniker: "<MONIKER>"                    # if not setup here not in inventory/all it get's derived from the hostname
+# mode: <MODE>                            # entry-gateway/exit-gateway/mixnode 
+# wireguard_enabled: <WIREGUARD_ENABLED>  # true/false
+
+# NOTE: Possible vars to incule on landing page, etc.
+# operator_name: "<OPERATOR_NAME>"
+
+packages:
+  - tmux
+  - speedtest-cli
+  - nano
+  - htop
+  - git
+  - zip
+  - nala
+  - curl
+  - neovim
+  - ca-certificates
+  - jq
+  - wget
+  - ufw

ansible/nym-node/playbooks/inventory/all

@@ -0,0 +1,34 @@
+[nym_nodes]
+# READ CONFIGURATION GUIDE:
+# https://nym.com//docs/operators/orchestration/ansible#configuration
+
+# VARIABLES INFO
+# required vars to set values per node: 
+# `ansible_host`, `hostname`, `location`
+
+# global vars can be set in the group_vars/all.yml, for example:
+# `email`, `ansible_user`, `moniker`, `description`,  `mode`, `wireguard_enabled`
+# othersise they must be set per node!
+
+############
+# TEMPLATE #
+############
+# node1 ansible_host=<YOUR_SERVER_IP> ansible_user=<USER> hostname=<HOSTNAME> location=<LOCATION> email=<EMAIL> mode=<MODE> wireguard_enabled=<true/false> moniker=<MONIKER> description=<DESCRIPTION>
+
+# remove all comments and exchange the <VARIABLES> with your real values for each node
+# without <> brackets
+
+# PRIORITY ORDER
+# anything setup globaly can be overwritten in this file per node  
+# if provided here, it takes priority over the global setting
+
+# EXAMPLES
+# exit + wireguard gateway:
+# node2 ansible_host=11.12.13.14 hostname=nym-exit.ch-1.mydomain.net mode=exit-gateway location=CH wireguard_enabled=true
+
+# entry gateway, no wireguard:
+# node3 ansible_host=12.13.14.15 hostname=nym-entry.ch-2.mydomain.net mode=entry-gateway location=CH wireguard_enabled=false
+
+# NOTE:
+# all examples above don't have defined user, email nor description as we use the definition from group_vars/main.yml without an attempt of overwriting it
+# all examples above don't have moniker defined as there is a function in /templates/description.toml.j2 deriving it from the hostname

ansible/nym-node/playbooks/upgrade.yml

@@ -0,0 +1,9 @@
+---
+- name: "Upgrade Nym node"
+  hosts: all    # or a specific host/group or limit via -l on CLI (ansible-playbook playbooks/upgrade.yml -l mynode1)
+  become: true
+  serial: 1
+  
+  roles:
+    - base
+    - upgrade

ansible/nym-node/roles/base/tasks/main.yml

@@ -0,0 +1,22 @@
+- name: Set hostname
+  hostname:
+    name: "{{ hostname }}"
+  when: hostname is defined and hostname | length > 0
+
+- name: Install aptitude 
+  apt:
+    name: aptitude
+    update_cache: yes
+    state: present
+    force_apt_get: yes
+
+- name: Update packages
+  apt:
+    update_cache: yes
+    upgrade: yes
+    
+- name: Install essential packages
+  package:
+    name: "{{ packages }}"
+    state: latest
+    update_cache: yes

ansible/nym-node/roles/nginx/tasks/main.yml

@@ -0,0 +1,61 @@
+- name: Install nginx and certbot
+  apt:
+    name:
+      - nginx
+      - certbot
+      - python3-certbot-nginx
+    state: present
+
+- name: Create web root directory
+  file:
+    path: "/var/www/{{ hostname }}"
+    state: directory
+    mode: "0755"
+
+- name: Create landing page template
+  tags: landing
+  template:
+    src: landing.html.j2
+    dest: "/var/www/{{ hostname }}/index.html"
+
+- name: Remove default nginx site
+  file:
+    path: /etc/nginx/sites-enabled/default
+    state: absent
+
+- name: Add bare-bones nginx template
+  template:
+    src: nginx-site.conf.j2
+    dest: "/etc/nginx/sites-available/{{ hostname }}"
+
+- name: Enable nginx config
+  file:
+    src: "/etc/nginx/sites-available/{{ hostname }}"
+    dest: "/etc/nginx/sites-enabled/{{ hostname }}"
+    state: link
+
+- name: Validate nginx configuration
+  command: nginx -t
+  changed_when: false
+
+- name: Obtain SSL certificate
+  command:
+    cmd: "certbot --nginx --non-interactive --agree-tos --redirect -m {{ email }} -d {{ hostname }}"
+
+- name: Add wss config from nginx template
+  template:
+    src: wss-config.conf.j2
+    dest: "/etc/nginx/sites-available/nym-wss-config"
+
+- name: Enable WSS config
+  file:
+    src: "/etc/nginx/sites-available/nym-wss-config"
+    dest: "/etc/nginx/sites-enabled/nym-wss-config"
+    state: link
+
+- name: Validate nginx config after wss
+  command: nginx -t
+  changed_when: false
+
+- name: Restart nginx to apply changes
+  service: name=nginx state=restarted enabled=yes

ansible/nym-node/roles/nginx/tasks/templates/landing.html.j2

@@ -0,0 +1,218 @@
+<!DOCTYPE html>
+<html lang="en-US">
+<head>
+<meta charset="UTF-8">
+<title>This is a NYM Exit Gateway</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="icon" type="image/png" href="">
+
+<style>
+:root {
+  /* font + theme tokens */
+  font-family: Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace;
+  --background-color: #242B2D;
+  --text-color: #FFFFFF;
+  --link-color: #07ff94;
+  --title-color: #07ff94;
+}
+
+html {
+  background: var(--background-color);
+}
+
+body {
+  margin-left: auto;
+  margin-right: auto;
+  padding-left: 5vw;
+  padding-right: 5vw;
+  max-width: 1000px;
+  color: var(--text-color); /* default text color */
+}
+
+h1 {
+  font-size: 55px;
+  text-align: center;
+  color: var(--title-color);
+}
+
+p {
+  color: var(--text-color);
+}
+
+p, a {
+  font-size: 20px;
+}
+
+a {
+  color: var(--link-color);
+  text-decoration: none;
+}
+
+a:hover {
+  filter: brightness(.8);
+  text-decoration: underline;
+}
+
+.links {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: space-evenly;
+}
+
+.links > a {
+  margin: 10px;
+  white-space: nowrap;
+}
+</style>
+</head>
+
+<body>
+<main>
+  <h1>This is a NYM Exit Gateway</h1>
+
+
+  <p>
+    You are most likely accessing this website because you've had some issue with
+    the traffic coming from this IP. This router is part of the <a
+    href="https://nym.com/">NYM project</a>, which is
+    dedicated to <a href="https://nym.com/about/mission">create</a> outstanding
+    privacy software that is legally compliant without sacrificing integrity or
+    having any backdoors.
+    This router IP should be generating no other traffic, unless it has been
+    compromised.
+  </p>
+
+  <p><strong>
+    If you are a representative of a company who feels that this router is being
+    used to violate the DMCA, please be aware that this machine does not host or
+    contain any illegal content. Also be aware that network infrastructure
+    maintainers are not liable for the type of content that passes over their
+    equipment, in accordance with <a
+    href="https://www.law.cornell.edu/uscode/text/17/512">DMCA
+    "safe harbor" provisions</a>. In other words, you will have just as much luck
+    sending a takedown notice to the Internet backbone providers.
+  </strong></p>
+
+  <p>
+    Nym Network is operated by a decentralised community of node operators
+    and stakers. Nym Network is trustless, meaning that no parts of the system
+    nor its operators have access to information that might compromise the privacy
+    of users. Nym software enacts a strict principle of data minimisation and has
+    no back doors. The Nym mixnet works by encrypting packets in several layers
+    and relaying those through a multi-layered network called a mixnet,  eventually
+    letting the traffic exit the Nym mixnet through an exit gateway like this one.
+    This design makes it impossible for a service to know which user is connecting to it,
+    since it can only see the IP-address of the Nym exit gateway:
+  </p>
+
+  <p style="text-align:center;margin:40px 0">
+    <svg xmlns="http://www.w3.org/2000/svg" width="500" viewBox="0 0 490.28 293.73" style="width:100%;max-width:600px" role="img" aria-label="Diagram of how a user connects through the Nym network">
+      <desc>Illustration showing how a user might connect to a service through the Nym Network. The user first sends their data through three daisy-chained encrypted Nym nodes that exist on three different continents. Then the last Nym node in the chain connects to the target service over the normal internet.</desc>
+      <defs>
+        <style>
+          .t {
+            fill: var(--text-color);
+            stroke: var(--text-color);
+          }
+        </style>
+      </defs>
+      <!-- (SVG content left unchanged) -->
+      <path fill="#6fc8b7" d="M257.89 69.4c-6.61-6.36-10.62-7.73-18.36-8.62-7.97-1.83-20.06-7.99-24.17-.67-3.29 5.85-18.2 12.3-16.87 2.08.92-7.03 11.06-13.28 17-17.37 8.69-5.99 24.97-2.87 26.1-10.28 1.04-6.86-8.33-13.22-8.55-2.3-.38 12.84-19.62 2.24-8.73-6.2 8.92-6.9 16.05-9.02 25.61-6.15 12.37 4.83 25.58-2.05 33.73-.71 12.37-2.01 24.69-5.25 37.39-3.96 13 .43 24.08-.14 37.06.63 9.8 1.58 16.5 2.87 26.37 3.6 6.6.48 17.68-.82 24.3 1.9 8.3 4.24.44 10.94-6.89 11.8-8.79 1.05-23.59-1.19-26.6 1.86-5.8 7.41 10.75 5.68 11.27 14.54.57 9.45-5.42 9.38-8.72 16-2.7 4.2.3 13.93-1.18 18.45-1.85 5.64-19.64 4.47-14.7 14.4 4.16 8.34 1.17 19.14-10.33 12.02-5.88-3.65-9.85-22.04-15.66-21.9-11.06.27-11.37 13.18-12.7 17.52-1.3 4.27-3.79 2.33-6-.63-3.54-4.76-7.75-14.22-12.01-17.32-6.12-4.46-10.75-1.17-15.55 2.83-5.63 4.69-8.78 7.82-7.46 16.5.78 9.1-12.9 15.84-14.98 24.09-2.61 10.32-2.57 22.12-8.81 31.47-4 5.98-14.03 20.12-21.27 14.97-7.5-5.34-7.22-14.6-9.56-23.08-2.5-9.02.6-17.35-2.57-26.2-2.45-6.82-6.23-14.54-13.01-13.24-6.5.92-15.08 1.38-19.23-2.97-5.65-5.93-6-10.1-6.61-18.56 1.65-6.94 5.79-12.64 10.38-18.63 3.4-4.42 17.45-10.39 25.26-7.83 10.35 3.38 17.43 10.5 28.95 8.57 3.12-.53 9.14-4.65 7.1-6.62zm-145.6 37.27c-4.96-1.27-11.57 1.13-11.8 6.94-1.48 5.59-4.82 10.62-5.8 16.32.56 6.42 4.34 12.02 8.18 16.97 3.72 3.85 8.58 7.37 9.3 13.1 1.24 5.88 1.6 11.92 2.28 17.87.34 9.37.95 19.67 7.29 27.16 4.26 3.83 8.4-2.15 6.52-6.3-.54-4.54-.6-9.11 1.01-13.27 4.2-6.7 7.32-10.57 12.44-16.64 5.6-7.16 12.74-11.75 14-20.9.56-4.26 5.72-13.86 1.7-16.72-3.14-2.3-15.83-4-18.86-6.49-2.36-1.71-3.86-9.2-9.86-12.07-4.91-3.1-10.28-6.73-16.4-5.97zm11.16-49.42c6.13-2.93 10.58-4.77 14.61-10.25 3.5-4.28 2.46-12.62-2.59-15.45-7.27-3.22-13.08 5.78-18.81 8.71-5.96 4.2-12.07-5.48-6.44-10.6 5.53-4.13.38-9.2-5.66-8.48-6.12.8-12.48-1.45-18.6-1.73-5.3-.7-10.13-1-15.45-1.37-5.37-.05-16.51-2.23-25.13.87-5.42 1.79-12.5 5.3-16.73 9.06-4.85 4.2.2 7.56 5.54 7.45 5.3-.22 16.8-5.36 20.16.98 3.68 8.13-5.82 18.29-5.2 26.69.1 6.2 3.37 11 4.74 16.98 1.62 5.94 6.17 10.45 10 15.14 4.7 5.06 13.06 6.3 19.53 8.23 7.46.14 3.34-9.23 3.01-14.11 1.77-7.15 8.49-7.82 12.68-13.5 7.14-7.72 16.41-13.4 24.34-18.62zM190.88 3.1c-4.69 0-13.33.04-18.17-.34-7.65.12-13.1-.62-19.48-1.09-3.67.39-9.09 3.34-5.28 7.04 3.8.94 7.32 4.92 7.1 9.31 1.32 4.68 1.2 11.96 6.53 13.88 4.76-.2 7.12-7.6 11.93-8.25 6.85-2.05 12.5-4.58 17.87-9.09 2.48-2.76 7.94-6.38 5.26-10.33-1.55-1.31-2.18-.64-5.76-1.13zm178.81 157.37c-2.66 10.08-5.88 24.97 9.4 15.43 7.97-5.72 12.58-2.02 17.47 1.15.5.43 2.65 9.2 7.19 8.53 5.43-2.1 11.55-5.1 14.96-11.2 2.6-4.62 3.6-12.39 2.76-13.22-3.18-3.43-6.24-11.03-7.7-15.1-.76-2.14-2.24-2.6-2.74-.4-2.82 12.85-6.04 1.22-10.12-.05-8.2-1.67-29.62 7.17-31.22 14.86z"/>
+      <g fill="none">
+        <path stroke="#cf63a6" stroke-linecap="round" stroke-width="2.76" d="M135.2 140.58c61.4-3.82 115.95-118.83 151.45-103.33"/>
+        <path stroke="#cf63a6" stroke-linecap="round" stroke-width="2.76" d="M74.43 46.66c38.15 8.21 64.05 42.26 60.78 93.92M286.65 37.25c-9.6 39.44-3.57 57.12-35.64 91.98"/>
+        <path stroke="#e4c101" stroke-dasharray="9.06,2.265" stroke-width="2.27" d="M397.92 162.52c-31.38 1.26-90.89-53.54-148.3-36.17"/>
+        <path stroke="#cf63a6" stroke-linecap="round" stroke-width="2.77" d="M17.6 245.88c14.35 0 14.4.05 28-.03"/>
+        <path stroke="#e3bf01" stroke-dasharray="9.06,2.265" stroke-width="2.27" d="M46.26 274.14c-17.52-.12-16.68.08-30.34.07"/>
+      </g>
+      <g transform="translate(120.8 -35.81)">
+        <circle cx="509.78" cy="68.74" r="18.12" fill="#240a3b" transform="translate(-93.3 38.03) scale(.50637)"/>
+        <circle cx="440.95" cy="251.87" r="18.12" fill="#240a3b" transform="translate(-93.3 38.03) scale(.50637)"/>
+        <circle cx="212.62" cy="272.19" r="18.12" fill="#240a3b" transform="translate(-93.3 38.03) scale(.50637)"/>
+        <circle cx="92.12" cy="87.56" r="18.12" fill="#240a3b" transform="translate(-93.3 38.03) scale(.50637)"/>
+        <circle cx="730.88" cy="315.83" r="18.12" fill="#67727b" transform="translate(-93.3 38.03) scale(.50637)"/>
+        <circle cx="-102.85" cy="282.18" r="9.18" fill="#240a3b"/>
+        <circle cx="-102.85" cy="309.94" r="9.18" fill="#67727b"/>
+      </g>
+      <g class="t">
+        <text xml:space="preserve" x="-24.76" y="10.37" stroke-width=".26" font-size="16.93" font-weight="700" style="line-height:1.25" transform="translate(27.79 2.5)" word-spacing="0"><tspan x="-24.76" y="10.37">The user</tspan></text>
+        <text xml:space="preserve" x="150.63" y="196.62" stroke-width=".26" font-size="16.93" font-weight="700" style="line-height:1.25" transform="translate(27.79 2.5)" word-spacing="0"><tspan x="150.63" y="196.62">This server</tspan></text>
+        <text xml:space="preserve" x="346.39" y="202.63" stroke-width=".26" font-size="16.93" font-weight="700" style="line-height:1.25" transform="translate(27.79 2.5)" word-spacing="0"><tspan x="346.39" y="202.63">Your service</tspan></text>
+        <text xml:space="preserve" x="34.52" y="249.07" stroke-width=".26" font-size="16.93" font-weight="700" style="line-height:1.25" transform="translate(27.79 2.5)" word-spacing="0"><tspan x="34.52" y="249.07">Nym network link</tspan></text>
+        <text xml:space="preserve" x="34.13" y="276.05" stroke-width=".26" font-size="16.93" font-weight="700" style="line-height:1.25" transform="translate(27.79 2.5)" word-spacing="0"><tspan x="34.13" y="276.05">Unencrypted link</tspan></text>
+        <path fill="none" stroke-linecap="round" stroke-width="1.67" d="M222.6 184.1c-2.6-15.27 8.95-23.6 18.43-38.86m186.75 45.61c-.68-10.17-9.4-17.68-18.08-23.49"/>
+        <path fill="none" stroke-linecap="round" stroke-width="1.67" d="M240.99 153.41c.35-3.41 1.19-6.17.04-8.17m-7.15 5.48c1.83-2.8 4.58-4.45 7.15-5.48"/>
+        <path fill="none" stroke-linecap="round" stroke-width="1.67" d="M412.43 173.21c-2.2-3.15-2.54-3.85-2.73-5.85m0 0c2.46-.65 3.85.01 6.67 1.24M61.62 40.8C48.89 36.98 36.45 27.54 36.9 18.96M61.62 40.8c.05-2.58-3.58-4.8-5.25-5.26m-2.65 6.04c1.8.54 6.8 1.31 7.9-.78"/>
+        <path fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="2.44" d="M1.22 229.4h247.74v63.1H1.22z"/>
+      </g>
+    </svg>
+  </p>
+
+  <p><a href="https://nym.com/about/mixnet">Read more about how Nym works.</a></p>
+
+  <p>
+    Nym relies on a growing ecosystem of users, developers and researcher partners
+    aligned with the mission to make sure Nym software is running, remains usable
+    and solves real problems. While Nym is not designed for malicious computer
+    users, it is true that they can use the network for malicious ends. This
+    is largely because criminals and hackers have significantly better access to
+    privacy and anonymity than do the regular users whom they prey upon. Criminals
+    can and do build, sell, and trade far larger and more powerful networks than
+    Nym on a daily basis. Thus, in the mind of this operator, the social need for
+    easily accessible censorship-resistant private, anonymous communication trumps
+    the risk of unskilled bad actors, who are almost always more easily uncovered
+    by traditional police work than by extensive monitoring and surveillance anyway.
+  </p>
+
+  <p>
+    In terms of applicable law, the best way to understand Nym is to consider it a
+    network of routers operating as common carriers, much like the Internet
+    backbone. However, unlike the Internet backbone routers, Nym mixnodes do not
+    contain identifiable routing information about the source of a packet and do
+    mix the user internet traffic with that of other users, making communications
+    private and protecting not just the user content but the metadata
+    (user's IP address, who the user talks to, when, where, from what device and
+    more) and no single Nym node can determine both the origin and destination
+    of a given transmission.
+  </p>
+
+  <p>
+    As such, there is nothing the operator of this Exit Gateway can do to help you
+    track the connection further. This Exit Gateway maintains no logs of any of the
+    Nym Network, so there is little that can be done to trace either legitimate or
+    illegitimate traffic and most importantly the operator cannot tell apart one from
+    the other because of the cryptography design making such selection impossible
+    for the operator. Attempts to seize this router will accomplish nothing.
+  </p>
+
+  <p>
+    To decentralise and enable privacy for a broad range of services, this
+    Exit Gateway adopts an <a href="https://nymtech.net/.wellknown/network-requester/exit-policy.txt">Exit Policy</a>
+    serving as a safeguard.
+  </p>
+
+  <p>
+    That being said, if you still have a complaint about the router, you may email the
+    <a href="mailto:{{ email }}">maintainer</a>. If complaints are related to a particular service that is being abused,
+    the maintainer will submit that to the NYM Operators Community in order to add it to the Exit Policy cited above.
+    The community governance can only blacklist entire IP:port destinations across the entire network.
+  </p>
+
+  <p>
+    You also have the option of blocking this IP address and others on the Nym network if you so desire.
+    The Nym project provides a <a href="https://nym.com/explorer">
+    web service</a> to fetch a list of all IP addresses of Nym Gateway Exit nodes that allow exiting to a
+    specified IP:port combination. Please be considerate when using these options.
+  </p>
+  <p style="text-align:center">
+    <img
+      class="logo"
+      src="https://raw.githubusercontent.com/nymtech/websites/main/www/nym.com/public/images/Nym_meta_Image.png"
+      alt=""
+      style="max-width:320px;width:100%;height:auto"
+      onerror="this.onerror=null;this.src='/images/nym_logo.png';"
+    />
+  </p>
+</main>
+</body>
+</html>

ansible/nym-node/roles/nginx/tasks/templates/nginx-site.conf.j2

@@ -0,0 +1,13 @@
+server {
+    listen 80;
+    listen [::]:80;
+
+    server_name {{ hostname }};
+
+    location / {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+}

ansible/nym-node/roles/nginx/tasks/templates/wss-config.conf.j2

@@ -0,0 +1,35 @@
+server {
+    listen 9001 ssl http2;
+    listen [::]:9001 ssl http2;
+
+    server_name {{ hostname }};
+
+    ssl_certificate /etc/letsencrypt/live/{{ hostname }}/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/{{ hostname }}/privkey.pem;
+    include /etc/letsencrypt/options-ssl-nginx.conf;
+    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+
+    access_log /var/log/nginx/access.log;
+    error_log  /var/log/nginx/error.log;
+
+    location /favicon.ico {
+        return 204;
+        access_log off;
+        log_not_found off;
+    }
+
+    location / {
+        add_header 'Access-Control-Allow-Origin' '*' always;
+        add_header 'Access-Control-Allow-Credentials' 'true' always;
+        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, HEAD' always;
+        add_header 'Access-Control-Allow-Headers' '*' always;
+
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "Upgrade";
+        proxy_set_header X-Forwarded-For $remote_addr;
+
+        proxy_pass http://localhost:9000;
+        proxy_intercept_errors on;
+    }
+}

ansible/nym-node/roles/nym/defaults/main.yml

@@ -0,0 +1,40 @@
+---
+# Where binaries live
+nym_install_dir: /root/nym-binaries
+
+# nym-node run arguments (defaults, can be overridden per host/group)
+http_bind_address: "0.0.0.0:8080"        # maps to --http-bind-address
+mixnet_bind_address: "0.0.0.0:1789"      # maps to --mixnet-bind-address
+
+
+# WireGuard boolean
+wireguard_enabled: "{{ wireguard_enabled | default(false) | bool }}"
+
+# Landing page base dir, hostname is appended in the task
+landing_page_assets_base_dir: "/var/www"
+
+# Flag toggles
+# accept_operator_terms: true              # controls --accept-operator-terms-and-conditions
+nym_write_flag: true                     # controls -w
+nym_init_only_flag: true                 # controls --init-only
+wss_port: 9001                           # controlls --announce-wss-port
+
+# Optional: extra flags if you want to append more later
+nym_extra_flags: ""
+
+# CLI URL (nym_version can be set elsewhere / via GitHub API)
+nym_cli_url: "https://github.com/nymtech/nym/releases/download/{{ nym_version }}/nym-cli"
+
+# UFW
+nym_ufw_enable: true
+
+nym_ufw_rules:
+  - { port: 22,    proto: tcp }
+  - { port: 80,    proto: tcp }
+  - { port: 443,   proto: tcp }
+  - { port: 1789,  proto: tcp }
+  - { port: 1790,  proto: tcp }
+  - { port: 8080,  proto: tcp }
+  - { port: 9000,  proto: tcp }
+  - { port: 9001,  proto: tcp }
+  - { port: 51822, proto: udp }

ansible/nym-node/roles/nym/files/script.sh

@@ -0,0 +1 @@
+#!/bin/bash

ansible/nym-node/roles/nym/handlers/main.yml

@@ -0,0 +1,3 @@
+- name: Reload systemd
+  systemd:
+    daemon_reload: yes

ansible/nym-node/roles/nym/tasks/config.yml

@@ -0,0 +1,38 @@
+---
+# Useful when the host is behind a NAT
+- name: Fetch the public IP address
+  command: "curl -4 canhazip.com"
+  register: ipv4
+  changed_when: false
+  failed_when: false
+
+- name: Set public IP address
+  set_fact:
+    public_ip: "{{ ipv4.stdout | default(ansible_default_ipv4.address) }}"
+
+- name: Initialize nym node
+  # Delete the part from --hostname onward if you run  mode=mixnode only
+  command:
+    cmd: >
+      {{ nym_install_dir }}/nym-node run
+      --mode {{ mode }}
+      --public-ips {{ public_ip }}
+      --http-bind-address {{ http_bind_address }}
+      --mixnet-bind-address {{ mixnet_bind_address }}
+      --location {{ location }}
+      {% if accept_operator_terms %}--accept-operator-terms-and-conditions{% endif %}
+
+      {{ nym_extra_flags }}
+
+      --hostname {{ hostname }}
+      --wireguard-enabled {{ wireguard_enabled }}
+      --landing-page-assets-path {{ landing_page_assets_base_dir }}/{{ hostname }}/
+      {% if nym_write_flag %}-w{% endif %}
+      {% if nym_init_only_flag %}--init-only{% endif %}
+      --announce-wss-port {{ wss_port }}
+
+
+- name: Update nym description
+  template:
+    src: description.toml.j2
+    dest: /root/.nym/nym-nodes/default-nym-node/data/description.toml

ansible/nym-node/roles/nym/tasks/firewall.yml

@@ -0,0 +1,25 @@
+- name: Configure UFW rules
+  ufw:
+    rule: allow
+    port: "{{ item.port }}"
+    proto: "{{ item.proto }}"
+    comment: "{{ item.comment | default(omit) }}"
+  loop: "{{ nym_ufw_rules }}"
+  loop_control:
+    label: "{{ item.port }}/{{ item.proto }}"
+  when:
+    - nym_ufw_enable
+    - item.when | default(true)
+
+- name: Allow bandwidth/topup rule inside WG tunnel
+  command: >
+    ufw allow in on nymwg to any port 51830 proto tcp comment 'bandwidth queries/topup'
+  when:
+    - nym_ufw_enable
+    - (wireguard_enabled | bool)
+
+- name: Enable UFW
+  ufw:
+    state: enabled
+  when:
+    nym_ufw_enable

ansible/nym-node/roles/nym/tasks/install.yml

@@ -0,0 +1,34 @@
+---
+- name: Create nym directory
+  file:
+    path: "{{ nym_install_dir }}"
+    state: directory
+    mode: "0755"
+
+- name: Get latest Nym release metadata
+  uri:
+    url: https://api.github.com/repos/nymtech/nym/releases/latest
+    return_content: yes
+  register: latest_release
+  when: nym_version is not defined or nym_version == 'latest'
+
+- name: Set nym_version from GitHub API
+  set_fact:
+    nym_version: "{{ latest_release.json.tag_name }}"
+  when: nym_version is not defined or nym_version == 'latest'
+
+- name: Set binary URL
+  set_fact:
+    binary_url: "https://github.com/nymtech/nym/releases/download/{{ nym_version }}/nym-node"
+
+- name: Download nym-node binary
+  get_url:
+    url: "{{ binary_url }}"
+    dest: "{{ nym_install_dir }}/nym-node"
+    mode: "0755"
+
+- name: Download nym-cli binary
+  get_url:
+    url: "{{ nym_cli_url }}"
+    dest: "{{ nym_install_dir }}/nym-cli"
+    mode: "0755"

ansible/nym-node/roles/nym/tasks/main.yml

@@ -0,0 +1,12 @@
+---
+- name: Install Nym binaries
+  import_tasks: install.yml
+
+- name: Configure Nym node
+  import_tasks: config.yml
+
+- name: Configure firewall for Nym
+  import_tasks: firewall.yml
+
+- name: Configure and start Nym service
+  import_tasks: service.yml

ansible/nym-node/roles/nym/tasks/service.yml

@@ -0,0 +1,15 @@
+---
+- name: Template systemd service
+  tags: systemctl
+  template:
+    src: nym-node.service.j2
+    dest: /etc/systemd/system/nym-node.service
+  notify: Reload systemd
+
+- name: Enable and start nym service
+  tags: systemctl
+  systemd:
+    name: nym-node
+    enabled: yes
+    state: started
+    daemon_reload: yes

ansible/nym-node/roles/nym/templates/description.toml.j2

@@ -0,0 +1,20 @@
+{# Priority:
+   1. Use moniker if provided in inventory
+   2. Else strip "nym-exit." prefix if hostname starts with it
+   3. Else use hostname unchanged
+#}
+
+{% if moniker is defined and moniker | length > 0 %}
+    {% set moniker_final = moniker %}
+{% else %}
+    {% if hostname is defined and hostname.startswith('nym-exit.') %}
+        {% set moniker_final = hostname | regex_replace('^nym-exit\\.', '') %}
+    {% else %}
+        {% set moniker_final = hostname %}
+    {% endif %}
+{% endif %}
+
+moniker = "{{ moniker_final }}"
+website = " {{ website }}"
+security_contact = "{{ email }}"
+details = "{{ description }}"

ansible/nym-node/roles/nym/templates/nym-node.service.j2

@@ -0,0 +1,15 @@
+[Unit]
+Description=Nym Node
+StartLimitInterval=350
+StartLimitBurst=10
+
+[Service]
+User={{ ansible_user }}
+LimitNOFILE=65536
+ExecStart=/root/nym-binaries/nym-node run --mode {{ mode }} --accept-operator-terms-and-conditions --wireguard-enabled {{ wireguard_enabled }}
+KillSignal=SIGINT
+Restart=on-failure
+RestartSec=30
+
+[Install]
+WantedBy=multi-user.target

ansible/nym-node/roles/postinstall/tasks/main.yml

@@ -0,0 +1,49 @@
+- name: Show which node is being bonded
+  tags: bonding
+  debug:
+    msg: "Bonding Nym node: {{ hostname }}"
+
+- name: Get bonding details
+  tags: bonding
+  command: "/root/nym-binaries/nym-node bonding-information"
+  register: bondinfo
+  changed_when: false
+
+- name: Display bonding info
+  tags: bonding
+  debug:
+    msg: "{{ item }}"
+  loop: "{{ bondinfo.stdout_lines }}"
+
+
+- name: Prompt operator to generate contract message in wallet
+  tags: bonding
+  pause:
+    prompt: |
+      ** Using the bonding information above:
+
+      1. Open your wallet  
+      2. Go to Bonding section
+      3. Fill Hostname and Identity key from the message printed above
+      4. Copy the CONTRACT MESSAGE that your wallet displays  
+      5. Paste it below and press Enter
+
+      Paste CONTRACT MESSAGE here:
+  register: contract_msg_input
+
+- name: Sign bonding contract message on the node
+  tags: bonding
+  command:
+    argv:
+      - /root/nym-binaries/nym-node
+      - sign
+      - --contract-msg
+      - "{{ contract_msg_input.user_input }}"
+      - --output
+      - json
+  register: sign_output
+
+- name: Display full signed message exactly as returned
+  tags: bonding
+  debug:
+    msg: "{{ sign_output.stdout }}"

ansible/nym-node/roles/quic/tasks/main.yml

@@ -0,0 +1,16 @@
+- name: Download quic_bridge_deployment.sh
+  tags: quic bridge deployment
+  get_url:
+    url: "{{ quic_bridge_deployment_url }}"
+    dest: "/root/nym-binaries/quic_bridge_deployment.sh"
+    mode: "0755"
+
+- name: Configure tunnel manager
+  tags: quic bridge deployment
+  become: true
+  command:
+    cmd: "/root/nym-binaries/quic_bridge_deployment.sh {{ item }}"
+  environment:
+    NONINTERACTIVE: "1"
+  loop:
+    - full_bridge_setup

ansible/nym-node/roles/tunnel/tasks/main.yml

@@ -0,0 +1,14 @@
+- name: Download network-tunnel-manager.sh
+  tags: network tunnel manager
+  get_url:
+    url: "{{ tunnel_manager_url }}"
+    dest: "/root/nym-binaries/network-tunnel-manager.sh"
+    mode: "0755"
+
+- name: Configure tunnel manager
+  tags: network tunnel manager
+  become: true
+  command:
+    cmd: "/root/nym-binaries/network-tunnel-manager.sh {{ item }}"
+  loop:
+    - complete_networking_configuration

ansible/nym-node/roles/upgrade/defaults/main.yml

@@ -0,0 +1,10 @@
+nym_binary_dir: /root/nym-binaries
+nym_binary_path: "{{ nym_binary_dir }}/nym-node"
+nym_backup_dir: "{{ nym_binary_dir }}/bak"
+nym_backup_path: "{{ nym_backup_dir }}/nym-node"
+nym_service_name: nym-node
+
+# nym_version: "v2025.21-mozzarella"
+# Optional: set this to pin a specific release tag in (e.g. v2025.21-mozzarella)
+# otherwise the GitHub “latest” release is used
+

ansible/nym-node/roles/upgrade/tasks/fetch_latest.yml

@@ -0,0 +1,30 @@
+- name: Get latest Nym release metadata
+  uri:
+    url: https://api.github.com/repos/nymtech/nym/releases/latest
+    return_content: yes
+  register: latest_release
+  when: nym_version is not defined and not ansible_check_mode
+
+- name: Set nym_version from GitHub API
+  set_fact:
+    nym_version: "{{ latest_release.json.tag_name }}"
+  when: nym_version is not defined and not ansible_check_mode
+
+- name: Show target Nym version tag
+  debug:
+    msg: "Target Nym release tag: {{ nym_version | default('latest (check-mode)') }}"
+
+- name: Generate binary_url from version
+  set_fact:
+    binary_url: >-
+      https://github.com/nymtech/nym/releases/download/{{ nym_version }}/nym-node
+  when: not ansible_check_mode
+
+- name: Download nym-node binary
+  get_url:
+    url: "{{ binary_url }}"
+    dest: "{{ nym_binary_path }}"
+    mode: "0755"
+  register: download_result
+  failed_when: false
+  when: not ansible_check_mode

ansible/nym-node/roles/upgrade/tasks/finalize.yml

@@ -0,0 +1,122 @@
+# run --version on the new binary
+- name: Check new nym-node version
+  command:
+    argv:
+      - "{{ nym_binary_path }}"
+      - --version
+  register: nym_new_version_cmd
+  failed_when: false
+  changed_when: false
+  when: not ansible_check_mode
+
+# show the full stdout so we don’t depend on regex parsing at all
+# show full upgraded version output, line by line
+- name: Show upgraded nym-node version info
+  debug:
+    msg: >-
+      {{
+        [
+          "New nym-node --version rc: " ~ (nym_new_version_cmd.rc | default('unset') | string),
+          "New nym-node --version output:"
+        ]
+        + (nym_new_version_cmd.stdout_lines | default([]))
+      }}
+  when: not ansible_check_mode
+
+# decide if upgrade is successful
+# success means: the binary executed without an error (rc == 0)
+- name: Determine if upgrade is successful
+  set_fact:
+    upgrade_ok: "{{ (nym_new_version_cmd.rc | default(1)) == 0 }}"
+  when: not ansible_check_mode
+
+# show the decision for debugging
+- name: Debug upgrade_ok decision
+  debug:
+    msg:
+      - "upgrade_ok: {{ upgrade_ok }}"
+  when: not ansible_check_mode
+
+#########
+# success
+#########
+
+# show the full version output to the user, line-by-line
+- name: Show upgraded nym-node version info
+  debug:
+    msg:
+      - "Upgraded nym-node version output:"
+      - "{{ nym_new_version_cmd.stdout_lines | default([]) }}"
+  when: not ansible_check_mode and upgrade_ok | default(false)
+
+
+# remove backup
+- name: Remove backup after successful upgrade
+  file:
+    path: "{{ nym_backup_path }}"
+    state: absent
+  when:
+    - not ansible_check_mode
+    - upgrade_ok | default(false)
+    - nym_node_bin.stat.exists | default(false)
+
+# restart service
+- name: Restart nym-node service after successful upgrade
+  systemd:
+    name: "{{ nym_service_name }}"
+    state: restarted
+  when: not ansible_check_mode and upgrade_ok | default(false)
+
+# report success
+- name: Report successful upgrade
+  debug:
+    msg: >-
+      Upgrade successful. nym-node binary executed correctly and the service has been restarted.
+  when: not ansible_check_mode and upgrade_ok | default(false)
+
+#########
+# failure
+#########
+
+- name: Restore previous nym-node binary after failed upgrade
+  copy:
+    src: "{{ nym_backup_path }}"
+    dest: "{{ nym_binary_path }}"
+    mode: "0755"
+    remote_src: true
+  when:
+    - not ansible_check_mode
+    - (upgrade_ok | default(false)) == false
+    - nym_node_bin.stat.exists | default(false)
+
+- name: Remove backup after rollback
+  file:
+    path: "{{ nym_backup_path }}"
+    state: absent
+  when:
+    - not ansible_check_mode
+    - (upgrade_ok | default(false)) == false
+    - nym_node_bin.stat.exists | default(false)
+
+# always restart the service with the restored binary
+- name: Restart nym-node service with previous version after failed upgrade
+  systemd:
+    name: "{{ nym_service_name }}"
+    state: restarted
+  when:
+    - not ansible_check_mode
+    - (upgrade_ok | default(false)) == false
+    - nym_node_bin.stat.exists | default(false)
+
+- name: Report failed upgrade and rollback
+  debug:
+    msg: >-
+      Upgrade NOT successful. The previous nym-node binary has been restored
+      and the nym-node service has been restarted with the old version.
+  when: not ansible_check_mode and (upgrade_ok | default(false)) == false
+
+# optional: hard-fail the play for CI environments
+#- name: Fail the play to signal upgrade failure
+#  fail:
+#    msg: "nym-node upgrade failed; rolled back to previous binary."
+#  when: not ansible_check_mode and (upgrade_ok | default(false)) == false

ansible/nym-node/roles/upgrade/tasks/main.yml

@@ -0,0 +1,8 @@
+- name: Prepare for nym-node upgrade (backup, stop service)
+  include_tasks: prepare.yml
+
+- name: Fetch and install latest nym-node binary
+  include_tasks: fetch_latest.yml
+
+- name: Verify new nym-node and finalize (restart or rollback)
+  include_tasks: finalize.yml

ansible/nym-node/roles/upgrade/tasks/prepare.yml

@@ -0,0 +1,69 @@
+# stop service before touching the binary
+- name: Stop nym-node service
+  systemd:
+    name: "{{ nym_service_name }}"
+    state: stopped
+  when: not ansible_check_mode
+
+# check if the current binary exists
+- name: Check existing nym-node binary
+  stat:
+    path: "{{ nym_binary_path }}"
+  register: nym_node_bin
+
+# capture current nym-node version (if present)
+- name: Capture current nym-node version (if present)
+  command:
+    argv:
+      - "{{ nym_binary_path }}"
+      - --version
+  register: nym_current_version_cmd
+  failed_when: false
+  changed_when: false
+  when:
+    - nym_node_bin.stat.exists
+    - not ansible_check_mode
+
+# show full current version output instead of trying to parse it
+# show full current version output, line by line
+- name: Show current nym-node version info
+  debug:
+    msg: >-
+      {{
+        [
+          "Current nym-node --version rc: " ~ (nym_current_version_cmd.rc | default('unset') | string),
+          "Current nym-node --version output:"
+        ]
+        + (nym_current_version_cmd.stdout_lines | default([]))
+      }}
+  when:
+    - nym_node_bin.stat.exists
+    - not ansible_check_mode
+
+# ensure backup directory exists
+- name: Ensure backup directory exists
+  file:
+    path: "{{ nym_backup_dir }}"
+    state: directory
+    mode: "0755"
+  when: not ansible_check_mode
+
+# backup existing nym-node binary
+- name: Backup existing nym-node binary
+  copy:
+    src: "{{ nym_binary_path }}"
+    dest: "{{ nym_backup_path }}"
+    remote_src: true
+    mode: "0755"
+  when:
+    - not ansible_check_mode
+    - nym_node_bin.stat.exists
+
+# remove current nym-node binary
+- name: Remove current nym-node binary
+  file:
+    path: "{{ nym_binary_path }}"
+    state: absent
+  when:
+    - not ansible_check_mode
+    - nym_node_bin.stat.exists

common/client-core/gateways-storage/.sqlx/query-06e743d143fcc4be20ca2af5e99b19f15d22fff72490473587a14cdc046fda32.json

@@ -6,14 +6,14 @@
       {
         "name": "exists",
         "ordinal": 0,
-        "type_info": "Int"
+        "type_info": "Integer"
       }
     ],
     "parameters": {
       "Right": 1
     },
     "nullable": [
-      null
+      false
     ]
   },
   "hash": "06e743d143fcc4be20ca2af5e99b19f15d22fff72490473587a14cdc046fda32"

common/client-core/gateways-storage/.sqlx/query-0e85ec18da67cf4e3df04ad80136571f6e920eb2290f20b1b8c5b0ab4b489985.json

@@ -1,44 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT * FROM remote_gateway_details WHERE gateway_id_bs58 = ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "gateway_id_bs58",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "gateway_owner_address",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "gateway_listener",
-        "ordinal": 2,
-        "type_info": "Text"
-      },
-      {
-        "name": "derived_aes128_ctr_blake3_hmac_keys_bs58",
-        "ordinal": 3,
-        "type_info": "Text"
-      },
-      {
-        "name": "derived_aes256_gcm_siv_key",
-        "ordinal": 4,
-        "type_info": "Blob"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      false,
-      true,
-      false,
-      true,
-      true
-    ]
-  },
-  "hash": "0e85ec18da67cf4e3df04ad80136571f6e920eb2290f20b1b8c5b0ab4b489985"
-}

common/client-core/gateways-storage/.sqlx/query-0f1dfb89f1eb39f4a58787af0f53a7a93afb7e4d2e54e2d38fd79d31c8575a54.json

@@ -1,12 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "\n                UPDATE remote_gateway_details\n                SET\n                    derived_aes128_ctr_blake3_hmac_keys_bs58 = ?,\n                    derived_aes256_gcm_siv_key = ?\n                WHERE gateway_id_bs58 = ?\n            ",
-  "describe": {
-    "columns": [],
-    "parameters": {
-      "Right": 3
-    },
-    "nullable": []
-  },
-  "hash": "0f1dfb89f1eb39f4a58787af0f53a7a93afb7e4d2e54e2d38fd79d31c8575a54"
-}

common/client-core/gateways-storage/.sqlx/query-2c113b37864f9fec7e64c0f8fdd38edcdf149acfd38c56a4db3bbf97bdb13210.json

@@ -1,6 +1,6 @@
 {
   "db_name": "SQLite",
-  "query": "\n                INSERT INTO custom_gateway_details(gateway_id_bs58, data) \n                VALUES (?, ?)\n            ",
+  "query": "\n                INSERT INTO custom_gateway_details(gateway_id_bs58, data)\n                VALUES (?, ?)\n            ",
   "describe": {
     "columns": [],
     "parameters": {
@@ -8,5 +8,5 @@
     },
     "nullable": []
   },
-  "hash": "b059bc3688b6b7f83f47048db9897720fd4e6f3211bf74030a9638f7bf6738e4"
+  "hash": "2c113b37864f9fec7e64c0f8fdd38edcdf149acfd38c56a4db3bbf97bdb13210"
 }

common/client-core/gateways-storage/.sqlx/query-4b739e12ea8d917cb17580337caeabb05f0e3ddbec04fdfa111d0fc86ba75505.json

@@ -0,0 +1,38 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT\n                rgd.gateway_id_bs58,\n                derived_aes256_gcm_siv_key,\n                gateway_listener,\n                fallback_listener\n            FROM\n                remote_gateway_details AS rgd\n            INNER JOIN\n                remote_gateway_shared_keys AS rgsk\n            ON\n                rgd.gateway_id_bs58 = rgsk.gateway_id_bs58\n            WHERE\n                rgd.gateway_id_bs58 = ?",
+  "describe": {
+    "columns": [
+      {
+        "name": "gateway_id_bs58",
+        "ordinal": 0,
+        "type_info": "Text"
+      },
+      {
+        "name": "derived_aes256_gcm_siv_key",
+        "ordinal": 1,
+        "type_info": "Blob"
+      },
+      {
+        "name": "gateway_listener",
+        "ordinal": 2,
+        "type_info": "Text"
+      },
+      {
+        "name": "fallback_listener",
+        "ordinal": 3,
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      true
+    ]
+  },
+  "hash": "4b739e12ea8d917cb17580337caeabb05f0e3ddbec04fdfa111d0fc86ba75505"
+}

common/client-core/gateways-storage/.sqlx/query-700a75acbcd90c74baa7823c40739a8ff8a26400c1d2bd45a689970bf1ba0e66.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "\n                INSERT INTO remote_gateway_shared_keys(gateway_id_bs58, derived_aes256_gcm_siv_key)\n                VALUES (?, ?)\n            ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": []
+  },
+  "hash": "700a75acbcd90c74baa7823c40739a8ff8a26400c1d2bd45a689970bf1ba0e66"
+}

common/client-core/gateways-storage/.sqlx/query-727598e516090da6d26e36d09062b60ccb76d6468f359891428c0bfb96ddd7ef.json

@@ -1,6 +1,6 @@
 {
   "db_name": "SQLite",
-  "query": "\n                INSERT INTO registered_gateway(gateway_id_bs58, registration_timestamp, gateway_type) \n                VALUES (?, ?, ?)\n            ",
+  "query": "\n                INSERT INTO registered_gateway(gateway_id_bs58, registration_timestamp, gateway_type)\n                VALUES (?, ?, ?)\n            ",
   "describe": {
     "columns": [],
     "parameters": {
@@ -8,5 +8,5 @@
     },
     "nullable": []
   },
-  "hash": "8909fd329e7e5fb16c4989b15b3d3a12bba1569520e01f6f074178e23d6ee89e"
+  "hash": "727598e516090da6d26e36d09062b60ccb76d6468f359891428c0bfb96ddd7ef"
 }

common/client-core/gateways-storage/.sqlx/query-a64a557ba87d4b2c7457857afa7ebc7d4f895fc4991da18ec02c9e250bea0fe0.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "\n                INSERT INTO remote_gateway_details(gateway_id_bs58, gateway_listener, fallback_listener)\n                VALUES (?, ?, ?)\n            ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": []
+  },
+  "hash": "a64a557ba87d4b2c7457857afa7ebc7d4f895fc4991da18ec02c9e250bea0fe0"
+}

common/client-core/gateways-storage/.sqlx/query-a6939bea03b10cde810a9a099bd597b4f51092e30a41c4085a8f8668f039f7c0.json

@@ -1,12 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "\n                INSERT INTO remote_gateway_details(gateway_id_bs58, derived_aes128_ctr_blake3_hmac_keys_bs58, derived_aes256_gcm_siv_key, gateway_owner_address, gateway_listener)\n                VALUES (?, ?, ?, ?, ?)\n            ",
-  "describe": {
-    "columns": [],
-    "parameters": {
-      "Right": 5
-    },
-    "nullable": []
-  },
-  "hash": "a6939bea03b10cde810a9a099bd597b4f51092e30a41c4085a8f8668f039f7c0"
-}

common/client-core/gateways-storage/Cargo.toml

@@ -9,7 +9,6 @@ rust-version.workspace = true
 
 [dependencies]
 async-trait.workspace = true
-cosmrs.workspace = true
 serde = { workspace = true, features = ["derive"] }
 thiserror.workspace = true
 time.workspace = true
@@ -20,6 +19,7 @@ zeroize = { workspace = true, features = ["zeroize_derive"] }
 
 nym-crypto = { path = "../../crypto", features = ["asymmetric"] }
 nym-gateway-requests = { path = "../../gateway-requests" }
+nym-gateway-client = { path = "../../client-libs/gateway-client" }
 
 [target."cfg(not(target_arch = \"wasm32\"))".dependencies.sqlx]
 workspace = true

common/client-core/gateways-storage/fs_gateways_migrations/20251126120000_remove_legacy_add_fallback.sql

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+CREATE TABLE remote_gateway_details_temp
+(
+    gateway_id_bs58                          TEXT NOT NULL UNIQUE PRIMARY KEY REFERENCES registered_gateway (gateway_id_bs58),
+    derived_aes256_gcm_siv_key               BLOB NOT NULL,
+    gateway_listener                         TEXT NOT NULL,
+    fallback_listener                        TEXT,
+    expiration_timestamp                     DATETIME NOT NULL
+);
+
+-- keep only registrations with a non null aes256 key
+INSERT INTO remote_gateway_details_temp SELECT gateway_id_bs58, derived_aes256_gcm_siv_key, gateway_listener, NULL, datetime(0, 'unixepoch') FROM remote_gateway_details WHERE derived_aes256_gcm_siv_key IS NOT NULL;
+
+DROP TABLE remote_gateway_details;
+ALTER TABLE remote_gateway_details_temp RENAME TO remote_gateway_details;
+
+-- delete registrations with no key
+DELETE FROM registered_gateway WHERE gateway_id_bs58 NOT IN ( SELECT gateway_id_bs58 FROM remote_gateway_details);

common/client-core/gateways-storage/src/backend/fs_backend/manager.rs

@@ -6,6 +6,7 @@ use crate::{
     types::{
         RawActiveGateway, RawCustomGatewayDetails, RawRegisteredGateway, RawRemoteGatewayDetails,
     },
+    RawGatewayPublishedData,
 };
 use sqlx::{
     sqlite::{SqliteAutoVacuum, SqliteSynchronous},
@@ -144,13 +145,11 @@ impl StorageManager {
         &self,
         gateway_id: &str,
     ) -> Result<RawRemoteGatewayDetails, sqlx::Error> {
-        sqlx::query_as!(
-            RawRemoteGatewayDetails,
-            "SELECT * FROM remote_gateway_details WHERE gateway_id_bs58 = ?",
-            gateway_id
-        )
-        .fetch_one(&self.connection_pool)
-        .await
+        // query_as! macro doesn't use fromRow
+        sqlx::query_as("SELECT * FROM remote_gateway_details WHERE gateway_id_bs58 = ?")
+            .bind(gateway_id)
+            .fetch_one(&self.connection_pool)
+            .await
     }
 
     pub(crate) async fn set_remote_gateway_details(
@@ -159,41 +158,36 @@ impl StorageManager {
     ) -> Result<(), sqlx::Error> {
         sqlx::query!(
             r#"
-                INSERT INTO remote_gateway_details(gateway_id_bs58, derived_aes128_ctr_blake3_hmac_keys_bs58, derived_aes256_gcm_siv_key, gateway_owner_address, gateway_listener)
+                INSERT INTO remote_gateway_details(gateway_id_bs58, derived_aes256_gcm_siv_key, gateway_listener, fallback_listener, expiration_timestamp)
                 VALUES (?, ?, ?, ?, ?)
             "#,
             remote.gateway_id_bs58,
-            remote.derived_aes128_ctr_blake3_hmac_keys_bs58,
             remote.derived_aes256_gcm_siv_key,
-            remote.gateway_owner_address,
-            remote.gateway_listener,
+            remote.published_data.gateway_listener,
+            remote.published_data.fallback_listener,
+            remote.published_data.expiration_timestamp
         )
             .execute(&self.connection_pool)
             .await?;
         Ok(())
     }
 
-    pub(crate) async fn update_remote_gateway_key(
+    pub(crate) async fn update_remote_gateway_published_data(
         &self,
         gateway_id_bs58: &str,
-        derived_aes128_ctr_blake3_hmac_keys_bs58: Option<&str>,
-        derived_aes256_gcm_siv_key: Option<&[u8]>,
+        published_data: &RawGatewayPublishedData,
     ) -> Result<(), sqlx::Error> {
         sqlx::query!(
             r#"
-                UPDATE remote_gateway_details
-                SET
-                    derived_aes128_ctr_blake3_hmac_keys_bs58 = ?,
-                    derived_aes256_gcm_siv_key = ?
-                WHERE gateway_id_bs58 = ?
+                UPDATE remote_gateway_details SET gateway_listener = ?, fallback_listener = ?, expiration_timestamp = ? WHERE gateway_id_bs58 = ?
             "#,
-            derived_aes128_ctr_blake3_hmac_keys_bs58,
-            derived_aes256_gcm_siv_key,
+            published_data.gateway_listener,
+            published_data.fallback_listener,
+            published_data.expiration_timestamp,
             gateway_id_bs58
         )
-        .execute(&self.connection_pool)
-        .await?;
-
+            .execute(&self.connection_pool)
+            .await?;
         Ok(())
     }
 

common/client-core/gateways-storage/src/backend/fs_backend/mod.rs

@@ -2,18 +2,16 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::{
-    ActiveGateway, BadGateway, GatewayDetails, GatewayRegistration, GatewayType,
-    GatewaysDetailsStore, StorageError,
+    ActiveGateway, BadGateway, GatewayDetails, GatewayPublishedData, GatewayRegistration,
+    GatewayType, GatewaysDetailsStore, StorageError,
 };
 use async_trait::async_trait;
 use manager::StorageManager;
 use nym_crypto::asymmetric::ed25519;
-use nym_gateway_requests::SharedSymmetricKey;
 use std::path::Path;
 
 pub mod error;
 mod manager;
-mod models;
 
 #[derive(Clone)]
 pub struct OnDiskGatewaysDetails {
@@ -134,16 +132,15 @@ impl GatewaysDetailsStore for OnDiskGatewaysDetails {
         Ok(())
     }
 
-    async fn upgrade_stored_remote_gateway_key(
+    async fn update_gateway_published_data(
         &self,
-        gateway_id: ed25519::PublicKey,
-        updated_key: &SharedSymmetricKey,
+        gateway_id: &ed25519::PublicKey,
+        published_data: &GatewayPublishedData,
     ) -> Result<(), Self::StorageError> {
         self.manager
-            .update_remote_gateway_key(
+            .update_remote_gateway_published_data(
                 &gateway_id.to_base58_string(),
-                None,
-                Some(updated_key.as_bytes()),
+                &published_data.into(),
             )
             .await?;
         Ok(())

common/client-core/gateways-storage/src/backend/fs_backend/models.rs

@@ -1,2 +0,0 @@
-// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0

common/client-core/gateways-storage/src/backend/mem_backend.rs

@@ -2,10 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::types::{ActiveGateway, GatewayRegistration};
-use crate::{BadGateway, GatewayDetails, GatewaysDetailsStore};
+use crate::{BadGateway, GatewayDetails, GatewayPublishedData, GatewaysDetailsStore};
 use async_trait::async_trait;
-use nym_crypto::asymmetric::ed25519::PublicKey;
-use nym_gateway_requests::{SharedGatewayKey, SharedSymmetricKey};
+use nym_crypto::asymmetric::ed25519;
 use std::collections::HashMap;
 use std::sync::Arc;
 use thiserror::Error;
@@ -96,26 +95,17 @@ impl GatewaysDetailsStore for InMemGatewaysDetails {
         Ok(())
     }
 
-    async fn upgrade_stored_remote_gateway_key(
+    async fn update_gateway_published_data(
         &self,
-        gateway_id: PublicKey,
-        updated_key: &SharedSymmetricKey,
+        gateway_id: &ed25519::PublicKey,
+        published_data: &GatewayPublishedData,
     ) -> Result<(), Self::StorageError> {
         let mut guard = self.inner.write().await;
-
-        #[allow(clippy::unwrap_used)]
-        if let Some(target) = guard.gateways.get_mut(&gateway_id.to_string()) {
-            let GatewayDetails::Remote(details) = &mut target.details else {
-                return Ok(());
-            };
-            assert_eq!(Arc::strong_count(&details.shared_key), 1);
-
-            // eh. that's nasty, but it's only ever used for ephemeral clients so should be fine for now...
-            details.shared_key = Arc::new(SharedGatewayKey::Current(
-                SharedSymmetricKey::try_from_bytes(updated_key.as_bytes()).unwrap(),
-            ))
+        if let Some(gateway) = guard.gateways.get_mut(&gateway_id.to_base58_string()) {
+            if let GatewayDetails::Remote(ref mut remote_details) = gateway.details {
+                remote_details.published_data = published_data.clone();
+            }
         }
-
         Ok(())
     }
 

common/client-core/gateways-storage/src/error.rs

@@ -18,16 +18,6 @@ pub enum BadGateway {
         source: Ed25519RecoveryError,
     },
 
-    #[error("the account owner of gateway {gateway_id} ({raw_owner}) is malformed: {source}")]
-    MalformedGatewayOwnerAccountAddress {
-        gateway_id: String,
-
-        raw_owner: String,
-
-        #[source]
-        source: cosmrs::ErrorReport,
-    },
-
     #[error("the shared keys provided for gateway {gateway_id} are malformed: {source}")]
     MalformedSharedKeys {
         gateway_id: String,
@@ -50,4 +40,12 @@ pub enum BadGateway {
         #[source]
         source: url::ParseError,
     },
+
+    #[error("the listening address ({raw_listener}) is malformed: {source}")]
+    MalformedListenerNoId {
+        raw_listener: String,
+
+        #[source]
+        source: url::ParseError,
+    },
 }

common/client-core/gateways-storage/src/lib.rs

@@ -6,7 +6,6 @@
 
 use async_trait::async_trait;
 use nym_crypto::asymmetric::ed25519;
-use nym_gateway_requests::SharedSymmetricKey;
 use std::error::Error;
 
 pub mod backend;
@@ -60,10 +59,11 @@ pub trait GatewaysDetailsStore {
         details: &GatewayRegistration,
     ) -> Result<(), Self::StorageError>;
 
-    async fn upgrade_stored_remote_gateway_key(
+    /// Update the gateway details
+    async fn update_gateway_published_data(
         &self,
-        gateway_id: ed25519::PublicKey,
-        updated_key: &SharedSymmetricKey,
+        gateway_id: &ed25519::PublicKey,
+        published_data: &GatewayPublishedData,
     ) -> Result<(), Self::StorageError>;
 
     /// Remove given gateway details from the underlying store.

common/client-core/gateways-storage/src/types.rs

@@ -2,20 +2,21 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::BadGateway;
-use cosmrs::AccountId;
 use nym_crypto::asymmetric::ed25519;
-use nym_gateway_requests::shared_key::{LegacySharedKeys, SharedGatewayKey, SharedSymmetricKey};
+use nym_gateway_client::client::GatewayListeners;
+use nym_gateway_requests::shared_key::SharedSymmetricKey;
 use serde::{Deserialize, Serialize};
 use std::fmt::{Display, Formatter};
-use std::ops::Deref;
 use std::str::FromStr;
 use std::sync::Arc;
+use time::Duration;
 use time::OffsetDateTime;
 use url::Url;
 use zeroize::{Zeroize, ZeroizeOnDrop};
 
 pub const REMOTE_GATEWAY_TYPE: &str = "remote";
 pub const CUSTOM_GATEWAY_TYPE: &str = "custom";
+const GATEWAY_DETAILS_TTL: Duration = Duration::days(7);
 
 #[derive(Debug, Clone, Default)]
 pub struct ActiveGateway {
@@ -65,15 +66,13 @@ impl From<GatewayDetails> for GatewayRegistration {
 impl GatewayDetails {
     pub fn new_remote(
         gateway_id: ed25519::PublicKey,
-        shared_key: Arc<SharedGatewayKey>,
-        gateway_owner_address: Option<AccountId>,
-        gateway_listener: Url,
+        shared_key: Arc<SharedSymmetricKey>,
+        published_data: GatewayPublishedData,
     ) -> Self {
         GatewayDetails::Remote(RemoteGatewayDetails {
             gateway_id,
             shared_key,
-            gateway_owner_address,
-            gateway_listener,
+            published_data,
         })
     }
 
@@ -88,13 +87,20 @@ impl GatewayDetails {
         }
     }
 
-    pub fn shared_key(&self) -> Option<&SharedGatewayKey> {
+    pub fn shared_key(&self) -> Option<&SharedSymmetricKey> {
         match self {
             GatewayDetails::Remote(details) => Some(&details.shared_key),
             GatewayDetails::Custom(_) => None,
         }
     }
 
+    pub fn details_exipration(&self) -> Option<OffsetDateTime> {
+        match self {
+            GatewayDetails::Remote(details) => Some(details.published_data.expiration_timestamp),
+            GatewayDetails::Custom(_) => None,
+        }
+    }
+
     pub fn is_custom(&self) -> bool {
         matches!(self, GatewayDetails::Custom(..))
     }
@@ -164,14 +170,78 @@ pub struct RegisteredGateway {
     pub gateway_type: GatewayType,
 }
 
+#[derive(Debug, Clone)]
+pub struct GatewayPublishedData {
+    pub listeners: GatewayListeners,
+    pub expiration_timestamp: OffsetDateTime,
+}
+
+impl GatewayPublishedData {
+    pub fn new(listeners: GatewayListeners) -> GatewayPublishedData {
+        GatewayPublishedData {
+            listeners,
+            expiration_timestamp: OffsetDateTime::now_utc() + GATEWAY_DETAILS_TTL,
+        }
+    }
+}
+
+#[derive(Debug, Serialize, Deserialize, Clone)]
+#[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))]
+pub struct RawGatewayPublishedData {
+    pub gateway_listener: String,
+    pub fallback_listener: Option<String>,
+    pub expiration_timestamp: OffsetDateTime,
+}
+
+impl<'a> From<&'a GatewayPublishedData> for RawGatewayPublishedData {
+    fn from(value: &'a GatewayPublishedData) -> Self {
+        Self {
+            gateway_listener: value.listeners.primary.to_string(),
+            fallback_listener: value.listeners.fallback.as_ref().map(|uri| uri.to_string()),
+            expiration_timestamp: value.expiration_timestamp,
+        }
+    }
+}
+
+impl TryFrom<RawGatewayPublishedData> for GatewayPublishedData {
+    type Error = BadGateway;
+
+    fn try_from(value: RawGatewayPublishedData) -> Result<Self, Self::Error> {
+        let gateway_listener: Url = Url::parse(&value.gateway_listener).map_err(|source| {
+            BadGateway::MalformedListenerNoId {
+                raw_listener: value.gateway_listener.clone(),
+                source,
+            }
+        })?;
+        let fallback_listener = value
+            .fallback_listener
+            .as_ref()
+            .map(|uri| {
+                Url::parse(uri).map_err(|source| BadGateway::MalformedListenerNoId {
+                    raw_listener: uri.to_owned(),
+                    source,
+                })
+            })
+            .transpose()?;
+
+        Ok(GatewayPublishedData {
+            listeners: GatewayListeners {
+                primary: gateway_listener,
+                fallback: fallback_listener,
+            },
+            expiration_timestamp: value.expiration_timestamp,
+        })
+    }
+}
+
 #[derive(Debug, Zeroize, ZeroizeOnDrop, Serialize, Deserialize)]
 #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))]
 pub struct RawRemoteGatewayDetails {
     pub gateway_id_bs58: String,
-    pub derived_aes128_ctr_blake3_hmac_keys_bs58: Option<String>,
-    pub derived_aes256_gcm_siv_key: Option<Vec<u8>>,
-    pub gateway_owner_address: Option<String>,
-    pub gateway_listener: String,
+    pub derived_aes256_gcm_siv_key: Vec<u8>,
+    #[zeroize(skip)]
+    #[cfg_attr(feature = "sqlx", sqlx(flatten))]
+    pub published_data: RawGatewayPublishedData,
 }
 
 impl TryFrom<RawRemoteGatewayDetails> for RemoteGatewayDetails {
@@ -186,81 +256,26 @@ impl TryFrom<RawRemoteGatewayDetails> for RemoteGatewayDetails {
                 }
             })?;
 
-        let shared_key =
-            match (
-                &value.derived_aes256_gcm_siv_key,
-                &value.derived_aes128_ctr_blake3_hmac_keys_bs58,
-            ) {
-                (None, None) => {
-                    return Err(BadGateway::MissingSharedKey {
-                        gateway_id: value.gateway_id_bs58.clone(),
-                    })
-                }
-                (Some(aes256gcm_siv), _) => {
-                    let current_key =
-                        SharedSymmetricKey::try_from_bytes(aes256gcm_siv).map_err(|source| {
-                            BadGateway::MalformedSharedKeys {
-                                gateway_id: value.gateway_id_bs58.clone(),
-                                source,
-                            }
-                        })?;
-                    SharedGatewayKey::Current(current_key)
-                }
-                (None, Some(aes128ctr_hmac)) => {
-                    let legacy_key = LegacySharedKeys::try_from_base58_string(aes128ctr_hmac)
-                        .map_err(|source| BadGateway::MalformedSharedKeys {
-                            gateway_id: value.gateway_id_bs58.clone(),
-                            source,
-                        })?;
-                    SharedGatewayKey::Legacy(legacy_key)
-                }
-            };
-
-        let gateway_owner_address = value
-            .gateway_owner_address
-            .as_ref()
-            .map(|raw_owner| {
-                AccountId::from_str(raw_owner).map_err(|source| {
-                    BadGateway::MalformedGatewayOwnerAccountAddress {
-                        gateway_id: value.gateway_id_bs58.clone(),
-                        raw_owner: raw_owner.clone(),
-                        source,
-                    }
-                })
-            })
-            .transpose()?;
-
-        let gateway_listener = Url::parse(&value.gateway_listener).map_err(|source| {
-            BadGateway::MalformedListener {
+        let shared_key = SharedSymmetricKey::try_from_bytes(&value.derived_aes256_gcm_siv_key)
+            .map_err(|source| BadGateway::MalformedSharedKeys {
                 gateway_id: value.gateway_id_bs58.clone(),
-                raw_listener: value.gateway_listener.clone(),
                 source,
-            }
-        })?;
+            })?;
 
         Ok(RemoteGatewayDetails {
             gateway_id,
             shared_key: Arc::new(shared_key),
-            gateway_owner_address,
-            gateway_listener,
+            published_data: value.published_data.clone().try_into()?,
         })
     }
 }
 
 impl<'a> From<&'a RemoteGatewayDetails> for RawRemoteGatewayDetails {
     fn from(value: &'a RemoteGatewayDetails) -> Self {
-        let (derived_aes128_ctr_blake3_hmac_keys_bs58, derived_aes256_gcm_siv_key) =
-            match value.shared_key.deref() {
-                SharedGatewayKey::Current(key) => (None, Some(key.to_bytes())),
-                SharedGatewayKey::Legacy(key) => (Some(key.to_base58_string()), None),
-            };
-
         RawRemoteGatewayDetails {
             gateway_id_bs58: value.gateway_id.to_base58_string(),
-            derived_aes128_ctr_blake3_hmac_keys_bs58,
-            derived_aes256_gcm_siv_key,
-            gateway_owner_address: value.gateway_owner_address.as_ref().map(|o| o.to_string()),
-            gateway_listener: value.gateway_listener.to_string(),
+            derived_aes256_gcm_siv_key: value.shared_key.to_bytes(),
+            published_data: (&value.published_data).into(),
         }
     }
 }
@@ -269,11 +284,9 @@ impl<'a> From<&'a RemoteGatewayDetails> for RawRemoteGatewayDetails {
 pub struct RemoteGatewayDetails {
     pub gateway_id: ed25519::PublicKey,
 
-    pub shared_key: Arc<SharedGatewayKey>,
+    pub shared_key: Arc<SharedSymmetricKey>,
 
-    pub gateway_owner_address: Option<AccountId>,
-
-    pub gateway_listener: Url,
+    pub published_data: GatewayPublishedData,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]

common/client-core/src/cli_helpers/client_add_gateway.rs

@@ -87,6 +87,7 @@ where
         user_chosen_gateway_id.map(|id| id.to_base58_string()),
         Some(common_args.latency_based_selection),
         common_args.force_tls_gateway,
+        false,
     );
     tracing::debug!("Gateway selection specification: {selection_spec:?}");
 
@@ -167,6 +168,7 @@ where
         identity: gateway_details.gateway_id,
         active: common_args.set_active,
         typ: gateway_registration.details.typ().to_string(),
-        endpoint: Some(gateway_details.gateway_listener.clone()),
+        endpoint: Some(gateway_details.published_data.listeners.primary.clone()),
+        fallback_endpoint: gateway_details.published_data.listeners.fallback.clone(),
     })
 }

common/client-core/src/cli_helpers/client_init.rs

@@ -140,6 +140,7 @@ where
         user_chosen_gateway_id.map(|id| id.to_base58_string()),
         Some(common_args.latency_based_selection),
         common_args.force_tls_gateway,
+        false,
     );
     tracing::debug!("Gateway selection specification: {selection_spec:?}");
 

common/client-core/src/cli_helpers/client_list_gateways.rs

@@ -56,7 +56,8 @@ where
                 identity: remote_details.gateway_id,
                 active: active_gateway == Some(remote_details.gateway_id),
                 typ: GatewayType::Remote.to_string(),
-                endpoint: Some(remote_details.gateway_listener),
+                endpoint: Some(remote_details.published_data.listeners.primary.clone()),
+                fallback_endpoint: remote_details.published_data.listeners.fallback.clone(),
             }),
             GatewayDetails::Custom(_) => info.push(GatewayInfo {
                 registration: gateway.registration_timestamp,
@@ -64,6 +65,7 @@ where
                 active: active_gateway == Some(gateway.details.gateway_id()),
                 typ: gateway.details.typ().to_string(),
                 endpoint: None,
+                fallback_endpoint: None,
             }),
         };
     }

common/client-core/src/cli_helpers/types.rs

@@ -15,6 +15,7 @@ pub struct GatewayInfo {
 
     pub typ: String,
     pub endpoint: Option<Url>,
+    pub fallback_endpoint: Option<Url>,
 }
 
 impl Display for GatewayInfo {
@@ -30,6 +31,9 @@ impl Display for GatewayInfo {
         if let Some(endpoint) = &self.endpoint {
             write!(f, " endpoint: {endpoint}")?;
         }
+        if let Some(fallback_endpoint) = &self.fallback_endpoint {
+            write!(f, " fallback: {fallback_endpoint}")?;
+        }
         Ok(())
     }
 }

common/client-core/src/client/base_client/mod.rs

@@ -529,7 +529,6 @@ where
         config: &Config,
         initialisation_result: InitialisationResult,
         bandwidth_controller: Option<BandwidthController<C, S::CredentialStore>>,
-        details_store: &S::GatewaysDetailsStore,
         packet_router: PacketRouter,
         stats_reporter: ClientStatsSender,
         #[cfg(unix)] connection_fd_callback: Option<Arc<dyn Fn(RawFd) + Send + Sync>>,
@@ -555,14 +554,7 @@ where
                     shutdown_tracker.clone_shutdown_token(),
                 )
             } else {
-                let cfg = GatewayConfig::new(
-                    details.gateway_id,
-                    details
-                        .gateway_owner_address
-                        .as_ref()
-                        .map(|o| o.to_string()),
-                    details.gateway_listener.to_string(),
-                );
+                let cfg = GatewayConfig::new(details.gateway_id, details.published_data.listeners);
                 GatewayClient::new(
                     GatewayClientConfig::new_default()
                         .with_disabled_credentials_mode(config.client.disabled_credentials_mode)
@@ -592,32 +584,13 @@ where
         // the gateway client startup procedure is slightly more complicated now
         // we need to:
         // - perform handshake (reg or auth)
-        // - check for key upgrade
-        // - maybe perform another upgrade handshake
         // - check for bandwidth
         // - start background tasks
-        let auth_res = gateway_client
+        let _ = gateway_client
             .perform_initial_authentication()
             .await
             .map_err(gateway_failure)?;
 
-        if auth_res.requires_key_upgrade {
-            // drop the shared_key arc because we don't need it and we can't hold it for the purposes of upgrade
-            drop(auth_res);
-
-            let updated_key = gateway_client
-                .upgrade_key_authenticated()
-                .await
-                .map_err(gateway_failure)?;
-
-            details_store
-                .upgrade_stored_remote_gateway_key(gateway_client.gateway_identity(), &updated_key)
-                .await.map_err(|err| {
-                tracing::error!("failed to store upgraded gateway key! this connection might be forever broken now: {err}");
-                ClientCoreError::GatewaysDetailsStoreError { source: Box::new(err) }
-            })?
-        }
-
         gateway_client
             .claim_initial_bandwidth()
             .await
@@ -636,7 +609,6 @@ where
         config: &Config,
         initialisation_result: InitialisationResult,
         bandwidth_controller: Option<BandwidthController<C, S::CredentialStore>>,
-        details_store: &S::GatewaysDetailsStore,
         packet_router: PacketRouter,
         stats_reporter: ClientStatsSender,
         #[cfg(unix)] connection_fd_callback: Option<Arc<dyn Fn(RawFd) + Send + Sync>>,
@@ -667,7 +639,6 @@ where
             config,
             initialisation_result,
             bandwidth_controller,
-            details_store,
             packet_router,
             stats_reporter,
             #[cfg(unix)]
@@ -975,8 +946,7 @@ where
         )
         .await?;
 
-        let (reply_storage_backend, credential_store, details_store) =
-            self.client_store.into_runtime_stores();
+        let (reply_storage_backend, credential_store, _) = self.client_store.into_runtime_stores();
 
         // channels for inter-component communication
         // TODO: make the channels be internally created by the relevant components
@@ -1069,7 +1039,6 @@ where
             &self.config,
             init_res,
             bandwidth_controller,
-            &details_store,
             gateway_packet_router,
             stats_reporter.clone(),
             #[cfg(unix)]

common/client-core/src/client/base_client/storage/helpers.rs

@@ -4,7 +4,9 @@
 use crate::client::key_manager::persistence::KeyStore;
 use crate::client::key_manager::ClientKeys;
 use crate::error::ClientCoreError;
-use nym_client_core_gateways_storage::{ActiveGateway, GatewayRegistration, GatewaysDetailsStore};
+use nym_client_core_gateways_storage::{
+    ActiveGateway, GatewayPublishedData, GatewayRegistration, GatewaysDetailsStore,
+};
 use nym_crypto::asymmetric::ed25519;
 
 // helpers for error wrapping
@@ -85,6 +87,23 @@ where
         })
 }
 
+pub async fn update_stored_published_data_gateway<D>(
+    details_store: &D,
+    gateway_id: &ed25519::PublicKey,
+    published_data: &GatewayPublishedData,
+) -> Result<(), ClientCoreError>
+where
+    D: GatewaysDetailsStore,
+    D::StorageError: Send + Sync + 'static,
+{
+    details_store
+        .update_gateway_published_data(gateway_id, published_data)
+        .await
+        .map_err(|source| ClientCoreError::GatewaysDetailsStoreError {
+            source: Box::new(source),
+        })
+}
+
 pub async fn load_active_gateway_details<D>(
     details_store: &D,
 ) -> Result<ActiveGateway, ClientCoreError>

common/client-core/src/client/base_client/storage/migration_helpers.rs

@@ -2,210 +2,18 @@
 // SPDX-License-Identifier: Apache-2.0
 
 pub mod v1_1_33 {
-    use crate::client::base_client::{
-        non_wasm_helpers::setup_fs_gateways_storage,
-        storage::helpers::{set_active_gateway, store_gateway_details},
-    };
     use crate::config::disk_persistence::old_v1_1_33::CommonClientPathsV1_1_33;
     use crate::config::disk_persistence::CommonClientPaths;
     use crate::config::old_config_v1_1_33::OldGatewayEndpointConfigV1_1_33;
     use crate::error::ClientCoreError;
-    use nym_client_core_gateways_storage::{
-        CustomGatewayDetails, GatewayDetails, GatewayRegistration, RemoteGatewayDetails,
-    };
-    use nym_gateway_requests::shared_key::LegacySharedKeys;
-    use serde::{Deserialize, Serialize};
-    use sha2::{digest::Digest, Sha256};
-    use std::ops::Deref;
-    use std::path::Path;
-    use std::sync::Arc;
-    use zeroize::Zeroizing;
-
-    mod base64 {
-        use base64::{engine::general_purpose::STANDARD, Engine as _};
-        use serde::{Deserialize, Deserializer, Serializer};
-
-        pub fn serialize<S: Serializer>(bytes: &[u8], serializer: S) -> Result<S::Ok, S::Error> {
-            serializer.serialize_str(&STANDARD.encode(bytes))
-        }
-
-        pub fn deserialize<'de, D: Deserializer<'de>>(
-            deserializer: D,
-        ) -> Result<Vec<u8>, D::Error> {
-            let s = <String>::deserialize(deserializer)?;
-            STANDARD.decode(s).map_err(serde::de::Error::custom)
-        }
-    }
-
-    #[derive(Debug, Clone, Serialize, Deserialize)]
-    #[serde(untagged)]
-    enum PersistedGatewayDetails {
-        /// Standard details of a remote gateway
-        Default(PersistedGatewayConfig),
-
-        /// Custom gateway setup, such as for a client embedded inside gateway itself
-        Custom(PersistedCustomGatewayDetails),
-    }
-
-    #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-    struct PersistedGatewayConfig {
-        /// The hash of the shared keys to ensure the correct ones are used with those gateway details.
-        #[serde(with = "base64")]
-        key_hash: Vec<u8>,
-
-        /// Actual gateway details being persisted.
-        details: OldGatewayEndpointConfigV1_1_33,
-    }
-
-    impl PersistedGatewayConfig {
-        fn verify(&self, shared_key: &LegacySharedKeys) -> bool {
-            let key_bytes = Zeroizing::new(shared_key.to_bytes());
-
-            let mut key_hasher = Sha256::new();
-            key_hasher.update(&key_bytes);
-            let key_hash = key_hasher.finalize();
-
-            self.key_hash == key_hash.deref()
-        }
-    }
-
-    #[derive(Debug, Clone, Serialize, Deserialize)]
-    struct PersistedCustomGatewayDetails {
-        gateway_id: String,
-    }
-
-    fn load_shared_key<P: AsRef<Path>>(path: P) -> Result<LegacySharedKeys, ClientCoreError> {
-        // the shared key was a simple pem file
-        Ok(nym_pemstore::load_key(path)?)
-    }
-
-    fn gateway_details_from_raw(
-        gateway_id: String,
-        gateway_owner: String,
-        gateway_listener: String,
-        gateway_shared_key: LegacySharedKeys,
-    ) -> Result<GatewayDetails, ClientCoreError> {
-        Ok(GatewayDetails::Remote(RemoteGatewayDetails {
-            gateway_id: gateway_id
-                .parse()
-                .map_err(|err| ClientCoreError::UpgradeFailure {
-                    message: format!("the stored gateway id was malformed: {err}"),
-                })?,
-            shared_key: Arc::new(gateway_shared_key.into()),
-            gateway_owner_address: Some(gateway_owner.parse().map_err(|err| {
-                ClientCoreError::UpgradeFailure {
-                    message: format!("the stored gateway owner address was malformed: {err}"),
-                }
-            })?),
-            gateway_listener: gateway_listener.parse().map_err(|err| {
-                ClientCoreError::UpgradeFailure {
-                    message: format!("the stored gateway listener address was malformed: {err}"),
-                }
-            })?,
-        }))
-    }
-
-    // helper to extract shared key and gateway details into the new GatewayRegistration
-    fn extract_gateway_registration(
-        storage_paths: &CommonClientPathsV1_1_33,
-    ) -> Result<GatewayRegistration, ClientCoreError> {
-        let details_file = std::fs::File::open(&storage_paths.gateway_details).map_err(|err| {
-            ClientCoreError::UpgradeFailure {
-                message: format!(
-                    "failed to open gateway details file at {}: {err}",
-                    storage_paths.gateway_details.display()
-                ),
-            }
-        })?;
-
-        // in v1.1.33 of the clients, the gateway details struct was saved as json
-        let details: PersistedGatewayDetails =
-            serde_json::from_reader(details_file).map_err(|err| {
-                ClientCoreError::UpgradeFailure {
-                    message: format!(
-                        "failed to deserialize gateway details from {}: {err}",
-                        storage_paths.gateway_details.display()
-                    ),
-                }
-            })?;
-
-        let details = match details {
-            PersistedGatewayDetails::Default(config) => {
-                let gateway_shared_key =
-                    load_shared_key(&storage_paths.keys.gateway_shared_key_file)?;
-                if !config.verify(&gateway_shared_key) {
-                    return Err(ClientCoreError::UpgradeFailure {
-                        message: "failed to verify consistency of the existing gateway details"
-                            .to_string(),
-                    });
-                }
-                gateway_details_from_raw(
-                    config.details.gateway_id,
-                    config.details.gateway_owner,
-                    config.details.gateway_listener,
-                    gateway_shared_key,
-                )?
-            }
-            PersistedGatewayDetails::Custom(custom) => {
-                GatewayDetails::Custom(CustomGatewayDetails {
-                    gateway_id: custom.gateway_id.parse().map_err(|err| {
-                        ClientCoreError::UpgradeFailure {
-                            message: format!("the stored gateway id was malformed: {err}"),
-                        }
-                    })?,
-                    data: None,
-                })
-            }
-        };
-
-        Ok(details.into())
-    }
-
-    // it's responsibility of the caller to ensure this is called **after** new registration has already been saved
-    fn remove_old_gateway_details(storage_paths: &CommonClientPathsV1_1_33) -> std::io::Result<()> {
-        std::fs::remove_file(&storage_paths.gateway_details)?;
-
-        if storage_paths.keys.gateway_shared_key_file.exists() {
-            std::fs::remove_file(&storage_paths.keys.gateway_shared_key_file)?;
-        }
-        Ok(())
-    }
 
     pub async fn migrate_gateway_details(
-        old_storage_paths: &CommonClientPathsV1_1_33,
-        new_storage_paths: &CommonClientPaths,
-        preloaded_config: Option<OldGatewayEndpointConfigV1_1_33>,
+        _old_storage_paths: &CommonClientPathsV1_1_33,
+        _new_storage_paths: &CommonClientPaths,
+        _preloaded_config: Option<OldGatewayEndpointConfigV1_1_33>,
     ) -> Result<(), ClientCoreError> {
-        let gateway_registration = match preloaded_config {
-            Some(config) => {
-                let gateway_shared_key =
-                    load_shared_key(&old_storage_paths.keys.gateway_shared_key_file)?;
-                gateway_details_from_raw(
-                    config.gateway_id,
-                    config.gateway_owner,
-                    config.gateway_listener,
-                    gateway_shared_key,
-                )?
-                .into()
-            }
-            None => extract_gateway_registration(old_storage_paths)?,
-        };
-
-        // since we're migrating to a brand new store, the store should be empty
-        // and thus set the 'new' gateway as the active one
-        let details_store =
-            setup_fs_gateways_storage(&new_storage_paths.gateway_registrations).await?;
-        store_gateway_details(&details_store, &gateway_registration).await?;
-        set_active_gateway(
-            &details_store,
-            &gateway_registration.details.gateway_id().to_base58_string(),
-        )
-        .await?;
-
-        remove_old_gateway_details(old_storage_paths).map_err(|err| {
-            ClientCoreError::UpgradeFailure {
-                message: format!("failed to remove old data: {err}"),
-            }
-        })
+        Err(ClientCoreError::UnsupportedMigration(
+            "migration of legacy keys has been removed and is no longer supported".into(),
+        ))
     }
 }

common/client-core/src/client/cover_traffic_stream.rs

@@ -32,9 +32,12 @@ where
     /// Key used to encrypt and decrypt content of an ACK packet.
     ack_key: Arc<AckKey>,
 
-    /// Average delay an acknowledgement packet is going to get delay at a single mixnode.
+    /// Average delay an acknowledgement packet is going to get delayed at a single mixnode.
     average_ack_delay: Duration,
 
+    /// Average delay a forward packet is going to get delayed at a single mixnode.
+    average_packet_delay: Duration,
+
     /// Defines configuration options related to cover traffic.
     cover_traffic: config::CoverTraffic,
 
@@ -122,6 +125,7 @@ impl LoopCoverTrafficStream<OsRng> {
         LoopCoverTrafficStream {
             ack_key,
             average_ack_delay,
+            average_packet_delay: traffic_config.average_packet_delay,
             cover_traffic: cover_config,
             next_delay,
             mix_tx,
@@ -187,7 +191,7 @@ impl LoopCoverTrafficStream<OsRng> {
             &self.ack_key,
             &self.our_full_destination,
             self.average_ack_delay,
-            self.cover_traffic.loop_cover_traffic_average_delay,
+            self.average_packet_delay,
             cover_traffic_packet_size,
             self.packet_type,
         ) {

common/client-core/src/client/key_manager/mod.rs

@@ -6,7 +6,7 @@ use nym_crypto::{
     asymmetric::{ed25519, x25519},
     hkdf::{DerivationMaterial, InvalidLength},
 };
-use nym_gateway_requests::shared_key::{LegacySharedKeys, SharedGatewayKey, SharedSymmetricKey};
+use nym_gateway_requests::shared_key::SharedSymmetricKey;
 use nym_sphinx::acknowledgements::AckKey;
 use rand::{CryptoRng, RngCore};
 use std::sync::Arc;
@@ -106,7 +106,5 @@ fn _assert_keys_zeroize_on_drop() {
     _assert_zeroize_on_drop::<ed25519::KeyPair>();
     _assert_zeroize_on_drop::<x25519::KeyPair>();
     _assert_zeroize_on_drop::<AckKey>();
-    _assert_zeroize_on_drop::<LegacySharedKeys>();
     _assert_zeroize_on_drop::<SharedSymmetricKey>();
-    _assert_zeroize_on_drop::<SharedGatewayKey>();
 }

common/client-core/src/error.rs

@@ -16,6 +16,9 @@ use std::path::PathBuf;
 
 #[derive(thiserror::Error, Debug)]
 pub enum ClientCoreError {
+    #[error("could not perform the state migration: {0}")]
+    UnsupportedMigration(String),
+
     #[error("I/O error: {0}")]
     IoError(#[from] std::io::Error),
 
@@ -43,6 +46,9 @@ pub enum ClientCoreError {
     #[error("Invalid URL: {0}")]
     InvalidUrl(String),
 
+    #[error("node doesn't advertise ip addresses : {0}")]
+    MissingIpAddress(String),
+
     #[cfg(not(target_arch = "wasm32"))]
     #[error("resolution failed: {0}")]
     ResolutionFailed(#[from] nym_http_api_client::ResolveError),
@@ -163,6 +169,9 @@ pub enum ClientCoreError {
     #[error("custom selection of gateway was expected")]
     CustomGatewaySelectionExpected,
 
+    #[error("custom selection of gateway was unexpected")]
+    UnexpectedCustomGatewaySelection,
+
     #[error("the persisted gateway details were set for a custom setup")]
     UnexpectedPersistedCustomGatewayDetails,
 

common/client-core/src/init/helpers.rs

@@ -5,6 +5,7 @@ use crate::error::ClientCoreError;
 use crate::init::types::RegistrationResult;
 use futures::{SinkExt, StreamExt};
 use nym_crypto::asymmetric::ed25519;
+use nym_gateway_client::client::GatewayListeners;
 use nym_gateway_client::GatewayClient;
 use nym_topology::node::RoutingNode;
 use nym_validator_client::client::{IdentityKeyRef, NymApiClientExt};
@@ -379,12 +380,12 @@ pub(super) fn get_specified_gateway(
 
 pub(super) async fn register_with_gateway(
     gateway_id: ed25519::PublicKey,
-    gateway_listener: Url,
+    gateway_listeners: GatewayListeners,
     our_identity: Arc<ed25519::KeyPair>,
     #[cfg(unix)] connection_fd_callback: Option<Arc<dyn Fn(RawFd) + Send + Sync>>,
 ) -> Result<RegistrationResult, ClientCoreError> {
     let mut gateway_client = GatewayClient::new_init(
-        gateway_listener,
+        gateway_listeners,
         gateway_id,
         our_identity.clone(),
         #[cfg(unix)]
@@ -409,14 +410,6 @@ pub(super) async fn register_with_gateway(
             }
         })?;
 
-    // this should NEVER happen, if it did, it means the function was misused,
-    // because for any fresh **registration**, the derived key is always up to date
-    if auth_response.requires_key_upgrade {
-        return Err(ClientCoreError::UnexpectedKeyUpgrade {
-            gateway_id: gateway_id.to_base58_string(),
-        });
-    }
-
     Ok(RegistrationResult {
         shared_keys: auth_response.initial_shared_key,
         authenticated_ephemeral_client: gateway_client,

common/client-core/src/init/mod.rs

@@ -5,7 +5,7 @@
 
 use crate::client::base_client::storage::helpers::{
     has_gateway_details, load_active_gateway_details, load_client_keys, load_gateway_details,
-    store_gateway_details,
+    store_gateway_details, update_stored_published_data_gateway,
 };
 use crate::client::key_manager::persistence::KeyStore;
 use crate::client::key_manager::ClientKeys;
@@ -16,8 +16,8 @@ use crate::init::helpers::{
 use crate::init::types::{
     GatewaySelectionSpecification, GatewaySetup, InitialisationResult, SelectedGateway,
 };
-use nym_client_core_gateways_storage::GatewaysDetailsStore;
 use nym_client_core_gateways_storage::{GatewayDetails, GatewayRegistration};
+use nym_client_core_gateways_storage::{GatewayPublishedData, GatewaysDetailsStore};
 use nym_gateway_client::client::InitGatewayClient;
 use nym_topology::node::RoutingNode;
 use rand::rngs::OsRng;
@@ -71,21 +71,28 @@ where
     let mut rng = OsRng;
 
     let selected_gateway = match selection_specification {
-        GatewaySelectionSpecification::UniformRemote { must_use_tls } => {
+        GatewaySelectionSpecification::UniformRemote {
+            must_use_tls,
+            no_hostname,
+        } => {
             let gateway = uniformly_random_gateway(&mut rng, &available_gateways, must_use_tls)?;
-            SelectedGateway::from_topology_node(gateway, must_use_tls)?
+            SelectedGateway::from_topology_node(gateway, must_use_tls, no_hostname)?
         }
-        GatewaySelectionSpecification::RemoteByLatency { must_use_tls } => {
+        GatewaySelectionSpecification::RemoteByLatency {
+            must_use_tls,
+            no_hostname,
+        } => {
             let gateway =
                 choose_gateway_by_latency(&mut rng, &available_gateways, must_use_tls).await?;
-            SelectedGateway::from_topology_node(gateway, must_use_tls)?
+            SelectedGateway::from_topology_node(gateway, must_use_tls, no_hostname)?
         }
         GatewaySelectionSpecification::Specified {
             must_use_tls,
+            no_hostname,
             identity,
         } => {
             let gateway = get_specified_gateway(&identity, &available_gateways, must_use_tls)?;
-            SelectedGateway::from_topology_node(gateway, must_use_tls)?
+            SelectedGateway::from_topology_node(gateway, must_use_tls, no_hostname)?
         }
         GatewaySelectionSpecification::Custom {
             gateway_identity,
@@ -105,15 +112,15 @@ where
     let (gateway_details, authenticated_ephemeral_client) = match selected_gateway {
         SelectedGateway::Remote {
             gateway_id,
-            gateway_owner_address,
-            gateway_listener,
+
+            gateway_listeners,
         } => {
             // if we're using a 'normal' gateway setup, do register
             let our_identity = client_keys.identity_keypair();
 
             let registration = helpers::register_with_gateway(
                 gateway_id,
-                gateway_listener.clone(),
+                gateway_listeners.clone(),
                 our_identity,
                 #[cfg(unix)]
                 connection_fd_callback,
@@ -123,8 +130,7 @@ where
                 GatewayDetails::new_remote(
                     gateway_id,
                     registration.shared_keys,
-                    gateway_owner_address,
-                    gateway_listener,
+                    GatewayPublishedData::new(gateway_listeners),
                 ),
                 Some(registration.authenticated_ephemeral_client),
             )
@@ -150,6 +156,46 @@ where
     })
 }
 
+pub async fn refresh_gateway_published_data<D>(
+    details_store: &D,
+    registration: GatewayRegistration,
+    available_gateways: Vec<RoutingNode>,
+    must_use_tls: bool,
+    no_hostname: bool,
+) -> Result<(), ClientCoreError>
+where
+    D: GatewaysDetailsStore,
+    D::StorageError: Send + Sync + 'static,
+{
+    let gateway_id = registration.gateway_id().to_base58_string();
+    tracing::trace!("Updating gateway details : {gateway_id}");
+
+    let gateway = get_specified_gateway(&gateway_id, &available_gateways, must_use_tls)?;
+    let selected_gateway = SelectedGateway::from_topology_node(gateway, must_use_tls, no_hostname)?;
+
+    let new_gateway_listeners = match selected_gateway {
+        SelectedGateway::Remote {
+            gateway_listeners, ..
+        } => gateway_listeners,
+        SelectedGateway::Custom { .. } => {
+            // this should not happen, as `from_topology_node` returns a Remote
+            Err(ClientCoreError::UnexpectedCustomGatewaySelection)?
+        }
+    };
+
+    let new_published_data = GatewayPublishedData::new(new_gateway_listeners);
+
+    // update gateway details
+    update_stored_published_data_gateway(
+        details_store,
+        &registration.gateway_id(),
+        &new_published_data,
+    )
+    .await?;
+
+    Ok(())
+}
+
 async fn use_loaded_gateway_details<K, D>(
     key_store: &K,
     details_store: &D,

common/client-core/src/init/types.rs

@@ -10,12 +10,11 @@ use nym_client_core_gateways_storage::{
     GatewayRegistration, GatewaysDetailsStore, RemoteGatewayDetails,
 };
 use nym_crypto::asymmetric::ed25519;
-use nym_gateway_client::client::InitGatewayClient;
-use nym_gateway_requests::shared_key::SharedGatewayKey;
+use nym_gateway_client::client::{GatewayListeners, InitGatewayClient};
+use nym_gateway_client::SharedSymmetricKey;
 use nym_sphinx::addressing::clients::Recipient;
 use nym_topology::node::RoutingNode;
 use nym_validator_client::client::IdentityKey;
-use nym_validator_client::nyxd::AccountId;
 use serde::Serialize;
 use std::fmt::{Debug, Display};
 #[cfg(unix)]
@@ -28,9 +27,7 @@ pub enum SelectedGateway {
     Remote {
         gateway_id: ed25519::PublicKey,
 
-        gateway_owner_address: Option<AccountId>,
-
-        gateway_listener: Url,
+        gateway_listeners: GatewayListeners,
     },
     Custom {
         gateway_id: ed25519::PublicKey,
@@ -42,24 +39,40 @@ impl SelectedGateway {
     pub fn from_topology_node(
         node: RoutingNode,
         must_use_tls: bool,
+        no_hostname: bool,
     ) -> Result<Self, ClientCoreError> {
         // for now, let's use 'old' behaviour, if you want to change it, you can pass it up the enum stack yourself : )
         let prefer_ipv6 = false;
 
-        let gateway_listener = if must_use_tls {
-            node.ws_entry_address_tls()
-                .ok_or(ClientCoreError::UnsupportedWssProtocol {
-                    gateway: node.identity_key.to_base58_string(),
-                })?
+        let (gateway_listener, fallback_listener) = if must_use_tls {
+            // WSS main, no fallback
+            let primary =
+                node.ws_entry_address_tls()
+                    .ok_or(ClientCoreError::UnsupportedWssProtocol {
+                        gateway: node.identity_key.to_base58_string(),
+                    })?;
+            (primary, None)
         } else {
-            node.ws_entry_address(prefer_ipv6)
-                .ok_or(ClientCoreError::UnsupportedEntry {
+            let (maybe_primary, fallback) =
+                node.ws_entry_address_with_fallback(prefer_ipv6, no_hostname);
+            (
+                maybe_primary.ok_or(ClientCoreError::UnsupportedEntry {
                     id: node.node_id,
                     identity: node.identity_key.to_base58_string(),
-                })?
+                })?,
+                fallback,
+            )
         };
 
-        let gateway_listener =
+        let fallback_listener_url = fallback_listener.and_then(|address| {
+            Url::parse(&address)
+                .inspect_err(|err| {
+                    tracing::warn!("Malformed fallback listener, none will be used : {err}")
+                })
+                .ok()
+        });
+
+        let gateway_listener_url =
             Url::parse(&gateway_listener).map_err(|source| ClientCoreError::MalformedListener {
                 gateway_id: node.identity_key.to_base58_string(),
                 raw_listener: gateway_listener,
@@ -68,8 +81,10 @@ impl SelectedGateway {
 
         Ok(SelectedGateway::Remote {
             gateway_id: node.identity_key,
-            gateway_owner_address: None,
-            gateway_listener,
+            gateway_listeners: GatewayListeners {
+                primary: gateway_listener_url,
+                fallback: fallback_listener_url,
+            },
         })
     }
 
@@ -98,7 +113,7 @@ impl SelectedGateway {
 /// - shared keys derived between ourselves and the node
 /// - an authenticated handle of an ephemeral handle created for the purposes of registration
 pub struct RegistrationResult {
-    pub shared_keys: Arc<SharedGatewayKey>,
+    pub shared_keys: Arc<SharedSymmetricKey>,
     pub authenticated_ephemeral_client: InitGatewayClient,
 }
 
@@ -145,20 +160,36 @@ impl InitialisationResult {
     pub fn gateway_id(&self) -> ed25519::PublicKey {
         self.gateway_registration.details.gateway_id()
     }
+
+    // indicates if the remote gateway details TTL has expired
+    pub fn exipred_details(&self) -> bool {
+        if let Some(expiration_timestamp) = self.gateway_registration.details.details_exipration() {
+            OffsetDateTime::now_utc() > expiration_timestamp
+        } else {
+            false
+        }
+    }
 }
 
 #[derive(Clone, Debug)]
 pub enum GatewaySelectionSpecification {
     /// Uniformly choose a random remote gateway.
-    UniformRemote { must_use_tls: bool },
+    UniformRemote {
+        must_use_tls: bool,
+        no_hostname: bool,
+    },
 
     /// Should the new, remote, gateway be selected based on latency.
-    RemoteByLatency { must_use_tls: bool },
+    RemoteByLatency {
+        must_use_tls: bool,
+        no_hostname: bool,
+    },
 
     /// Gateway with this specific identity should be chosen.
     // JS: I don't really like the name of this enum variant but couldn't think of anything better at the time
     Specified {
         must_use_tls: bool,
+        no_hostname: bool,
         identity: IdentityKey,
     },
 
@@ -174,6 +205,7 @@ impl Default for GatewaySelectionSpecification {
     fn default() -> Self {
         GatewaySelectionSpecification::UniformRemote {
             must_use_tls: false,
+            no_hostname: false,
         }
     }
 }
@@ -183,16 +215,24 @@ impl GatewaySelectionSpecification {
         gateway_identity: Option<String>,
         latency_based_selection: Option<bool>,
         must_use_tls: bool,
+        no_hostname: bool,
     ) -> Self {
         if let Some(identity) = gateway_identity {
             GatewaySelectionSpecification::Specified {
                 identity,
                 must_use_tls,
+                no_hostname,
             }
         } else if let Some(true) = latency_based_selection {
-            GatewaySelectionSpecification::RemoteByLatency { must_use_tls }
+            GatewaySelectionSpecification::RemoteByLatency {
+                must_use_tls,
+                no_hostname,
+            }
         } else {
-            GatewaySelectionSpecification::UniformRemote { must_use_tls }
+            GatewaySelectionSpecification::UniformRemote {
+                must_use_tls,
+                no_hostname,
+            }
         }
     }
 }
@@ -315,6 +355,7 @@ pub struct InitResults {
     pub encryption_key: String,
     pub gateway_id: String,
     pub gateway_listener: String,
+    pub fallback_listener: Option<String>,
     pub gateway_registration: OffsetDateTime,
     pub address: Recipient,
 }
@@ -332,7 +373,13 @@ impl InitResults {
             identity_key: address.identity().to_base58_string(),
             encryption_key: address.encryption_key().to_base58_string(),
             gateway_id: gateway.gateway_id.to_base58_string(),
-            gateway_listener: gateway.gateway_listener.to_string(),
+            gateway_listener: gateway.published_data.listeners.primary.to_string(),
+            fallback_listener: gateway
+                .published_data
+                .listeners
+                .fallback
+                .as_ref()
+                .map(|uri| uri.to_string()),
             gateway_registration: registration,
             address,
         }

common/client-libs/gateway-client/src/client/mod.rs

@@ -21,8 +21,8 @@ use nym_crypto::asymmetric::ed25519;
 use nym_gateway_requests::registration::handshake::client_handshake;
 use nym_gateway_requests::{
     BandwidthResponse, BinaryRequest, ClientControlRequest, ClientRequest, GatewayProtocolVersion,
-    GatewayProtocolVersionExt, GatewayRequestsError, SensitiveServerResponse, ServerResponse,
-    SharedGatewayKey, SharedSymmetricKey, CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION,
+    GatewayProtocolVersionExt, GatewayRequestsError, ServerResponse, SharedSymmetricKey,
+    CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION, CURRENT_PROTOCOL_VERSION,
 };
 use nym_sphinx::forwarding::packet::MixPacket;
 use nym_statistics_common::clients::connection::ConnectionStatsEvent;
@@ -47,43 +47,39 @@ use std::os::raw::c_int as RawFd;
 use wasm_utils::websocket::JSWebsocket;
 #[cfg(target_arch = "wasm32")]
 use wasmtimer::tokio::sleep;
-use zeroize::Zeroizing;
 
 pub mod config;
 
 #[cfg(not(target_arch = "wasm32"))]
 pub(crate) mod websockets;
 #[cfg(not(target_arch = "wasm32"))]
-use websockets::connect_async;
+use crate::client::websockets::connect_async_with_fallback;
 
 pub struct GatewayConfig {
     pub gateway_identity: ed25519::PublicKey,
 
-    // currently a dead field
-    pub gateway_owner: Option<String>,
-
-    pub gateway_listener: String,
+    pub gateway_listeners: GatewayListeners,
 }
 
 impl GatewayConfig {
-    pub fn new(
-        gateway_identity: ed25519::PublicKey,
-        gateway_owner: Option<String>,
-        gateway_listener: String,
-    ) -> Self {
+    pub fn new(gateway_identity: ed25519::PublicKey, gateway_listeners: GatewayListeners) -> Self {
         GatewayConfig {
             gateway_identity,
-            gateway_owner,
-            gateway_listener,
+            gateway_listeners,
         }
     }
 }
 
+#[derive(Debug, Clone)]
+pub struct GatewayListeners {
+    pub primary: Url,
+    pub fallback: Option<Url>,
+}
+
 #[must_use]
 #[derive(Debug)]
 pub struct AuthenticationResponse {
-    pub initial_shared_key: Arc<SharedGatewayKey>,
-    pub requires_key_upgrade: bool,
+    pub initial_shared_key: Arc<SharedSymmetricKey>,
 }
 
 // TODO: this should be refactored into a state machine that keeps track of its authentication state
@@ -92,10 +88,10 @@ pub struct GatewayClient<C, St = EphemeralCredentialStorage> {
 
     authenticated: bool,
     bandwidth: ClientBandwidth,
-    gateway_address: String,
+    gateway_addresses: GatewayListeners,
     gateway_identity: ed25519::PublicKey,
     local_identity: Arc<ed25519::KeyPair>,
-    shared_key: Option<Arc<SharedGatewayKey>>,
+    shared_key: Option<Arc<SharedSymmetricKey>>,
     connection: SocketState,
     packet_router: PacketRouter,
     bandwidth_controller: Option<BandwidthController<C, St>>,
@@ -118,7 +114,7 @@ impl<C, St> GatewayClient<C, St> {
         gateway_config: GatewayConfig,
         local_identity: Arc<ed25519::KeyPair>,
         // TODO: make it mandatory. if you don't want to pass it, use `new_init`
-        shared_key: Option<Arc<SharedGatewayKey>>,
+        shared_key: Option<Arc<SharedSymmetricKey>>,
         packet_router: PacketRouter,
         bandwidth_controller: Option<BandwidthController<C, St>>,
         stats_reporter: ClientStatsSender,
@@ -129,7 +125,7 @@ impl<C, St> GatewayClient<C, St> {
             cfg,
             authenticated: false,
             bandwidth: ClientBandwidth::new_empty(),
-            gateway_address: gateway_config.gateway_listener,
+            gateway_addresses: gateway_config.gateway_listeners,
             gateway_identity: gateway_config.gateway_identity,
             local_identity,
             shared_key,
@@ -148,7 +144,7 @@ impl<C, St> GatewayClient<C, St> {
         self.gateway_identity
     }
 
-    pub fn shared_key(&self) -> Option<Arc<SharedGatewayKey>> {
+    pub fn shared_key(&self) -> Option<Arc<SharedSymmetricKey>> {
         self.shared_key.clone()
     }
 
@@ -203,12 +199,19 @@ impl<C, St> GatewayClient<C, St> {
 
     #[cfg(not(target_arch = "wasm32"))]
     pub async fn establish_connection(&mut self) -> Result<(), GatewayClientError> {
-        debug!(
-            "Attempting to establish connection to gateway at: {}",
-            self.gateway_address
-        );
-        let (ws_stream, _) = connect_async(
-            &self.gateway_address,
+        if let Some(fallback_url) = &self.gateway_addresses.fallback {
+            debug!(
+                "Attempting to establish connection to gateway at: {}, with fallback at: {fallback_url}",
+                self.gateway_addresses.primary
+            );
+        } else {
+            debug!(
+                "Attempting to establish connection to gateway at: {}",
+                self.gateway_addresses.primary
+            );
+        }
+        let (ws_stream, _) = connect_async_with_fallback(
+            &self.gateway_addresses,
             #[cfg(unix)]
             self.connection_fd_callback.clone(),
         )
@@ -221,7 +224,7 @@ impl<C, St> GatewayClient<C, St> {
 
     #[cfg(target_arch = "wasm32")]
     pub async fn establish_connection(&mut self) -> Result<(), GatewayClientError> {
-        let ws_stream = match JSWebsocket::new(&self.gateway_address) {
+        let ws_stream = match JSWebsocket::new(self.gateway_addresses.primary.as_ref()) {
             Ok(ws_stream) => ws_stream,
             Err(e) => {
                 return Err(GatewayClientError::NetworkErrorWasm(e));
@@ -274,7 +277,7 @@ impl<C, St> GatewayClient<C, St> {
         message: ClientRequest,
     ) -> Result<(), GatewayClientError> {
         if let Some(shared_key) = self.shared_key() {
-            let encrypted = message.encrypt(&*shared_key)?;
+            let encrypted = message.encrypt(&shared_key)?;
             Box::pin(self.send_websocket_message_without_response(encrypted)).await?;
             Ok(())
         } else {
@@ -463,19 +466,14 @@ impl<C, St> GatewayClient<C, St> {
 
     async fn register(
         &mut self,
-        supported_gateway_protocol: Option<GatewayProtocolVersion>,
+        supported_gateway_protocol: GatewayProtocolVersion,
     ) -> Result<(), GatewayClientError> {
         if !self.connection.is_established() {
             return Err(GatewayClientError::ConnectionNotEstablished);
         }
 
-        let derive_aes256_gcm_siv_key = supported_gateway_protocol.supports_aes256_gcm_siv();
-
         debug_assert!(self.connection.is_available());
-        log::debug!(
-            "registering with gateway. using legacy key derivation: {}",
-            !derive_aes256_gcm_siv_key
-        );
+        log::debug!("registering with gateway");
 
         // it's fine to instantiate it here as it's only used once (during authentication or registration)
         // and putting it into the GatewayClient struct would be a hassle
@@ -525,75 +523,6 @@ impl<C, St> GatewayClient<C, St> {
         Ok(())
     }
 
-    pub async fn upgrade_key_authenticated(
-        &mut self,
-    ) -> Result<Zeroizing<SharedSymmetricKey>, GatewayClientError> {
-        info!("*** STARTING AES128CTR-HMAC KEY UPGRADE INTO AES256GCM-SIV***");
-
-        if !self.connection.is_established() {
-            return Err(GatewayClientError::ConnectionNotEstablished);
-        }
-
-        if !self.authenticated {
-            return Err(GatewayClientError::NotAuthenticated);
-        }
-
-        let Some(shared_key) = self.shared_key.as_ref() else {
-            return Err(GatewayClientError::NoSharedKeyAvailable);
-        };
-
-        if !shared_key.is_legacy() {
-            return Err(GatewayClientError::KeyAlreadyUpgraded);
-        }
-
-        // make sure we have the only reference, so we could safely swap it
-        if Arc::strong_count(shared_key) != 1 {
-            return Err(GatewayClientError::KeyAlreadyInUse);
-        }
-
-        assert!(shared_key.is_legacy());
-        let legacy_key = shared_key.unwrap_legacy();
-        let (updated_key, hkdf_salt) = legacy_key.upgrade();
-        let derived_key_digest = updated_key.digest();
-
-        let upgrade_request = ClientRequest::UpgradeKey {
-            hkdf_salt,
-            derived_key_digest,
-        }
-        .encrypt(legacy_key)?;
-
-        info!("sending upgrade request and awaiting the acknowledgement back");
-        let (ciphertext, nonce) = match self
-            .send_websocket_message_with_response(upgrade_request)
-            .await?
-        {
-            ServerResponse::EncryptedResponse { ciphertext, nonce } => (ciphertext, nonce),
-            ServerResponse::Error { message } => {
-                return Err(GatewayClientError::GatewayError(message))
-            }
-            other => return Err(GatewayClientError::UnexpectedResponse { name: other.name() }),
-        };
-
-        // attempt to decrypt it using NEW key
-        let Ok(response) = SensitiveServerResponse::decrypt(&ciphertext, &nonce, &updated_key)
-        else {
-            return Err(GatewayClientError::FatalKeyUpgradeFailure);
-        };
-
-        match response {
-            SensitiveServerResponse::KeyUpgradeAck { .. } => {
-                info!("received key upgrade acknowledgement")
-            }
-            _ => return Err(GatewayClientError::FatalKeyUpgradeFailure),
-        }
-
-        // perform in memory swap and make a copy for updating storage
-        let zeroizing_updated_key = updated_key.zeroizing_clone();
-        self.shared_key = Some(Arc::new(updated_key.into()));
-
-        Ok(zeroizing_updated_key)
-    }
-
     async fn send_authenticate_request_and_handle_response(
         &mut self,
         msg: ClientControlRequest,
@@ -606,17 +535,14 @@ impl<C, St> GatewayClient<C, St> {
                 upgrade_mode,
             } => {
                 if protocol_version.is_future_version() {
-                    // SAFETY: future version is always defined
-                    #[allow(clippy::unwrap_used)]
-                    let version = protocol_version.unwrap();
-                    error!("the gateway insists on using v{version} protocol which is not supported by this client");
+                    error!("the gateway insists on using v{protocol_version} protocol which is not supported by this client");
                     return Err(GatewayClientError::AuthenticationFailure);
                 }
                 self.authenticated = status;
                 self.bandwidth
                     .update_and_maybe_log(bandwidth_remaining, upgrade_mode);
 
-                self.negotiated_protocol = protocol_version;
+                self.negotiated_protocol = Some(protocol_version);
                 log::debug!("authenticated: {status}, bandwidth remaining: {bandwidth_remaining}");
                 if upgrade_mode {
                     warn!("the system is currently undergoing an upgrade. some of its functionalities might be unstable")
@@ -629,27 +555,6 @@ impl<C, St> GatewayClient<C, St> {
         }
     }
 
-    async fn authenticate_v1(&mut self) -> Result<(), GatewayClientError> {
-        debug!("using v1 authentication");
-
-        let Some(shared_key) = self.shared_key.as_ref() else {
-            return Err(GatewayClientError::NoSharedKeyAvailable);
-        };
-
-        let self_address = self
-            .local_identity
-            .public_key()
-            .derive_destination_address();
-
-        let msg = ClientControlRequest::new_legacy_authenticate(
-            self_address,
-            shared_key,
-            self.cfg.bandwidth.require_tickets,
-        )?;
-        self.send_authenticate_request_and_handle_response(msg)
-            .await
-    }
-
     async fn authenticate_v2(
         &mut self,
         requested_protocol_version: GatewayProtocolVersion,
@@ -670,30 +575,22 @@ impl<C, St> GatewayClient<C, St> {
 
     async fn authenticate(
         &mut self,
-        supported_gateway_protocol: Option<GatewayProtocolVersion>,
+        requested_protocol_version: GatewayProtocolVersion,
     ) -> Result<(), GatewayClientError> {
         if !self.connection.is_established() {
             return Err(GatewayClientError::ConnectionNotEstablished);
         }
         debug!("authenticating with gateway");
 
-        if supported_gateway_protocol.supports_authenticate_v2() {
-            // use the highest possible protocol version the gateway has announced support for
-
-            // SAFETY: if announced protocol supports auth v2, it means it's properly set
-            #[allow(clippy::unwrap_used)]
-            self.authenticate_v2(supported_gateway_protocol.unwrap())
-                .await
-        } else {
-            self.authenticate_v1().await
-        }
+        // use the highest possible protocol version the gateway has announced support for
+        self.authenticate_v2(requested_protocol_version).await
     }
 
     /// Helper method to either call register or authenticate based on self.shared_key value
     #[instrument(skip_all,
         fields(
             gateway = %self.gateway_identity,
-            gateway_address = %self.gateway_address
+            gateway_address = %self.gateway_addresses.primary
         )
     )]
     pub async fn perform_initial_authentication(
@@ -704,15 +601,9 @@ impl<C, St> GatewayClient<C, St> {
         }
 
         // 1. check gateway's protocol version
-        let gw_protocol = match self.get_gateway_protocol().await {
-            Ok(protocol) => Some(protocol),
-            Err(_) => {
-                // if we failed to send the request, it means the gateway is running the old binary,
-                // so it has reset our connection - we have to reconnect
-                self.establish_connection().await?;
-                None
-            }
-        };
+        // if we failed to get this request resolved, it means the gateway is on an old version
+        // that definitely does not support auth v2 or aes256gcm, so we bail
+        let gw_protocol = self.get_gateway_protocol().await?;
 
         debug!("supported gateway protocol: {gw_protocol:?}");
 
@@ -727,6 +618,16 @@ impl<C, St> GatewayClient<C, St> {
         if !supports_auth_v2 {
             warn!("this gateway is on an old version that doesn't support authentication v2")
         }
+
+        // Dropping v1 support
+        if !supports_auth_v2 || !supports_aes_gcm_siv {
+            // we can't continue
+            return Err(GatewayClientError::IncompatibleProtocol {
+                gateway: gw_protocol,
+                current: CURRENT_PROTOCOL_VERSION,
+            });
+        }
+
         if !supports_key_rotation_info {
             warn!("this gateway is on an old version that doesn't support key rotation packets")
         }
@@ -736,7 +637,7 @@ impl<C, St> GatewayClient<C, St> {
 
         let gw_protocol = if gw_protocol.is_future_version() {
             warn!("we're running outdated software as gateway is announcing protocol {gw_protocol:?} whilst we're using {}. we're going to attempt to downgrade", GatewayProtocolVersion::CURRENT);
-            Some(GatewayProtocolVersion::CURRENT)
+            GatewayProtocolVersion::CURRENT
         } else {
             gw_protocol
         };
@@ -746,7 +647,6 @@ impl<C, St> GatewayClient<C, St> {
             return if let Some(shared_key) = &self.shared_key {
                 Ok(AuthenticationResponse {
                     initial_shared_key: Arc::clone(shared_key),
-                    requires_key_upgrade: shared_key.is_legacy() && supports_aes_gcm_siv,
                 })
             } else {
                 Err(GatewayClientError::AuthenticationFailureWithPreexistingSharedKey)
@@ -761,11 +661,8 @@ impl<C, St> GatewayClient<C, St> {
                 #[allow(clippy::unwrap_used)]
                 let shared_key = self.shared_key.as_ref().unwrap();
 
-                let requires_key_upgrade = shared_key.is_legacy() && supports_aes_gcm_siv;
-
                 Ok(AuthenticationResponse {
                     initial_shared_key: Arc::clone(shared_key),
-                    requires_key_upgrade,
                 })
             } else {
                 Err(GatewayClientError::AuthenticationFailure)
@@ -781,7 +678,6 @@ impl<C, St> GatewayClient<C, St> {
             // so no upgrades are required
             Ok(AuthenticationResponse {
                 initial_shared_key: Arc::clone(shared_key),
-                requires_key_upgrade: false,
             })
         }
     }
@@ -1143,7 +1039,12 @@ impl<C, St> GatewayClient<C, St> {
         }
 
         // if we're reconnecting, because we lost connection, we need to re-authenticate the connection
-        self.authenticate(self.negotiated_protocol).await?;
+        if let Some(negotiated_protocol) = self.negotiated_protocol {
+            self.authenticate(negotiated_protocol).await?;
+        } else {
+            // This should never happen, because it would mean we're not registered
+            return Err(GatewayClientError::NotRegistered);
+        }
 
         // this call is NON-blocking
         self.start_listening_for_mixnet_messages()?;
@@ -1188,7 +1089,7 @@ pub struct InitOnly;
 impl GatewayClient<InitOnly, EphemeralCredentialStorage> {
     // for initialisation we do not need credential storage. Though it's still a bit weird we have to set the generic...
     pub fn new_init(
-        gateway_listener: Url,
+        gateway_listeners: GatewayListeners,
         gateway_identity: ed25519::PublicKey,
         local_identity: Arc<ed25519::KeyPair>,
         #[cfg(unix)] connection_fd_callback: Option<Arc<dyn Fn(RawFd) + Send + Sync>>,
@@ -1207,7 +1108,7 @@ impl GatewayClient<InitOnly, EphemeralCredentialStorage> {
             cfg: GatewayClientConfig::default().with_disabled_credentials_mode(true),
             authenticated: false,
             bandwidth: ClientBandwidth::new_empty(),
-            gateway_address: gateway_listener.to_string(),
+            gateway_addresses: gateway_listeners,
             gateway_identity,
             local_identity,
             shared_key: None,
@@ -1239,7 +1140,7 @@ impl GatewayClient<InitOnly, EphemeralCredentialStorage> {
             cfg: self.cfg,
             authenticated: self.authenticated,
             bandwidth: self.bandwidth,
-            gateway_address: self.gateway_address,
+            gateway_addresses: self.gateway_addresses,
             gateway_identity: self.gateway_identity,
             local_identity: self.local_identity,
             shared_key: self.shared_key,

common/client-libs/gateway-client/src/client/websockets.rs

@@ -1,3 +1,5 @@
+#[cfg(not(target_arch = "wasm32"))]
+use crate::client::GatewayListeners;
 use crate::error::GatewayClientError;
 
 use nym_http_api_client::HickoryDnsResolver;
@@ -85,3 +87,35 @@ pub(crate) async fn connect_async(
             source: Box::new(error),
         })
 }
+
+#[cfg(not(target_arch = "wasm32"))]
+pub(crate) async fn connect_async_with_fallback(
+    endpoints: &GatewayListeners,
+    #[cfg(unix)] connection_fd_callback: Option<Arc<dyn Fn(RawFd) + Send + Sync>>,
+) -> Result<(WebSocketStream<MaybeTlsStream<TcpStream>>, Response), GatewayClientError> {
+    match connect_async(
+        endpoints.primary.as_ref(),
+        #[cfg(unix)]
+        connection_fd_callback.clone(),
+    )
+    .await
+    {
+        Ok(inner) => Ok(inner),
+        Err(e) => {
+            if let Some(fallback) = &endpoints.fallback {
+                tracing::warn!(
+                    "Main endpoint failed {} : {e}, trying fallback : {fallback}",
+                    endpoints.primary
+                );
+                connect_async(
+                    fallback.as_ref(),
+                    #[cfg(unix)]
+                    connection_fd_callback,
+                )
+                .await
+            } else {
+                Err(e)
+            }
+        }
+    }
+}

common/client-libs/gateway-client/src/error.rs

@@ -83,6 +83,9 @@ pub enum GatewayClientError {
     #[error("Client is not authenticated")]
     NotAuthenticated,
 
+    #[error("Client is not registered")]
+    NotRegistered,
+
     #[error("Client does not have enough bandwidth: estimated {0}, remaining: {1}")]
     NotEnoughBandwidth(i64, i64),
 
@@ -116,8 +119,8 @@ pub enum GatewayClientError {
     #[error("Failed to send mixnet message")]
     MixnetMsgSenderFailedToSend,
 
-    #[error("Attempted to negotiate connection with gateway using incompatible protocol version. Ours is {current} and the gateway reports {gateway:?}")]
-    IncompatibleProtocol { gateway: Option<u8>, current: u8 },
+    #[error("Attempted to negotiate connection with gateway using incompatible protocol version. Ours is {current} and the gateway reports {gateway}")]
+    IncompatibleProtocol { gateway: u8, current: u8 },
 
     #[error(
         "The packet router hasn't been set - are you sure you started up the client correctly?"

common/client-libs/gateway-client/src/lib.rs

@@ -7,9 +7,7 @@ use tracing::{error, warn};
 use tungstenite::{protocol::Message, Error as WsError};
 
 pub use client::{config::GatewayClientConfig, GatewayClient, GatewayConfig};
-pub use nym_gateway_requests::shared_key::{
-    LegacySharedKeys, SharedGatewayKey, SharedSymmetricKey,
-};
+pub use nym_gateway_requests::shared_key::SharedSymmetricKey;
 pub use packet_router::{
     AcknowledgementReceiver, AcknowledgementSender, MixnetMessageReceiver, MixnetMessageSender,
     PacketRouter,
@@ -47,7 +45,7 @@ pub(crate) fn cleanup_socket_messages(
 
 pub(crate) fn try_decrypt_binary_message(
     bin_msg: Vec<u8>,
-    shared_keys: &SharedGatewayKey,
+    shared_keys: &SharedSymmetricKey,
 ) -> Option<Vec<u8>> {
     match BinaryResponse::try_from_encrypted_tagged_bytes(bin_msg, shared_keys) {
         Ok(bin_response) => match bin_response {

common/client-libs/gateway-client/src/socket_state.rs

@@ -10,7 +10,7 @@ use crate::{cleanup_socket_messages, try_decrypt_binary_message};
 use futures::channel::oneshot;
 use futures::stream::{SplitSink, SplitStream};
 use futures::{SinkExt, StreamExt};
-use nym_gateway_requests::shared_key::SharedGatewayKey;
+use nym_gateway_requests::shared_key::SharedSymmetricKey;
 use nym_gateway_requests::{
     SendResponse, SensitiveServerResponse, ServerResponse, SimpleGatewayRequestsError,
 };
@@ -66,7 +66,7 @@ pub(crate) struct PartiallyDelegatedHandle {
 
 struct PartiallyDelegatedRouter {
     packet_router: PacketRouter,
-    shared_key: Arc<SharedGatewayKey>,
+    shared_key: Arc<SharedSymmetricKey>,
     client_bandwidth: ClientBandwidth,
 
     stream_return: SplitStreamSender,
@@ -76,7 +76,7 @@ struct PartiallyDelegatedRouter {
 impl PartiallyDelegatedRouter {
     fn new(
         packet_router: PacketRouter,
-        shared_key: Arc<SharedGatewayKey>,
+        shared_key: Arc<SharedSymmetricKey>,
         client_bandwidth: ClientBandwidth,
         stream_return: SplitStreamSender,
         stream_return_requester: oneshot::Receiver<()>,
@@ -214,11 +214,6 @@ impl PartiallyDelegatedRouter {
                         SensitiveServerResponse::RememberMeAck {} => {
                             info!("received remember me acknowledgement");
                         }
-                        SensitiveServerResponse::KeyUpgradeAck {} => {
-                            warn!(
-                                    "received illegal key upgrade acknowledgement in an authenticated client"
-                                );
-                        }
                         _ => {
                             warn!("received unknown SensitiveServerResponse");
                         }
@@ -294,7 +289,7 @@ impl PartiallyDelegatedHandle {
     pub(crate) fn split_and_listen_for_mixnet_messages(
         conn: WsConn,
         packet_router: PacketRouter,
-        shared_key: Arc<SharedGatewayKey>,
+        shared_key: Arc<SharedSymmetricKey>,
         client_bandwidth: ClientBandwidth,
         shutdown: ShutdownToken,
     ) -> Self {

common/gateway-requests/src/authentication/encrypted_address.rs

@@ -1,73 +0,0 @@
-// Copyright 2020-2024 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0
-
-use crate::shared_key::{SharedGatewayKey, SharedKeyUsageError};
-use nym_sphinx::DestinationAddressBytes;
-use thiserror::Error;
-
-/// Replacement for what used to be an `AuthToken`.
-///
-/// Replacement for what used to be an `AuthToken`. We used to be generating an `AuthToken` based on
-/// local secret and remote address in order to allow for authentication. Due to changes in registration
-/// and the fact we are deriving a shared key, we are encrypting remote's address with the previously
-/// derived shared key. If the value is as expected, then authentication is successful.
-#[derive(Debug, PartialEq, Eq, Hash, Clone)]
-// this is no longer constant size due to the differences in ciphertext between aes128ctr and aes256gcm-siv (inclusion of tag)
-pub struct EncryptedAddressBytes(Vec<u8>);
-
-impl From<Vec<u8>> for EncryptedAddressBytes {
-    fn from(encrypted_address: Vec<u8>) -> Self {
-        EncryptedAddressBytes(encrypted_address)
-    }
-}
-
-#[derive(Debug, Error)]
-pub enum EncryptedAddressConversionError {
-    #[error("Failed to decode the encrypted address - {0}")]
-    DecodeError(#[from] bs58::decode::Error),
-}
-
-impl EncryptedAddressBytes {
-    pub fn new(
-        address: &DestinationAddressBytes,
-        key: &SharedGatewayKey,
-        nonce: &[u8],
-    ) -> Result<Self, SharedKeyUsageError> {
-        let ciphertext = key.encrypt_naive(address.as_bytes_ref(), Some(nonce))?;
-
-        Ok(EncryptedAddressBytes(ciphertext))
-    }
-
-    pub fn verify(
-        &self,
-        address: &DestinationAddressBytes,
-        key: &SharedGatewayKey,
-        nonce: &[u8],
-    ) -> bool {
-        let Ok(reconstructed) = Self::new(address, key, nonce) else {
-            return false;
-        };
-        self == &reconstructed
-    }
-
-    pub fn as_bytes(&self) -> &[u8] {
-        &self.0
-    }
-
-    pub fn try_from_base58_string<S: Into<String>>(
-        val: S,
-    ) -> Result<Self, EncryptedAddressConversionError> {
-        let decoded = bs58::decode(val.into()).into_vec()?;
-        Ok(EncryptedAddressBytes(decoded))
-    }
-
-    pub fn to_base58_string(self) -> String {
-        bs58::encode(self.0).into_string()
-    }
-}
-
-impl From<EncryptedAddressBytes> for String {
-    fn from(val: EncryptedAddressBytes) -> Self {
-        val.to_base58_string()
-    }
-}

common/gateway-requests/src/authentication/mod.rs

@@ -1,4 +0,0 @@
-// Copyright 2020 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0
-
-pub mod encrypted_address;

common/gateway-requests/src/lib.rs

@@ -7,17 +7,12 @@ use nym_sphinx::params::GatewayIntegrityHmacAlgorithm;
 
 pub use types::*;
 
-pub mod authentication;
 pub mod models;
 pub mod registration;
 pub mod shared_key;
 pub mod types;
 
-pub use shared_key::helpers::SymmetricKey;
-pub use shared_key::legacy::{LegacySharedKeySize, LegacySharedKeys};
-pub use shared_key::{
-    SharedGatewayKey, SharedKeyConversionError, SharedKeyUsageError, SharedSymmetricKey,
-};
+pub use shared_key::{SharedKeyConversionError, SharedKeyUsageError, SharedSymmetricKey};
 
 pub type GatewayProtocolVersion = u8;
 
@@ -29,7 +24,7 @@ pub const CURRENT_PROTOCOL_VERSION: GatewayProtocolVersion = UPGRADE_MODE_VERSIO
 // 1 - initial release
 // 2 - changes to client credentials structure
 // 3 - change to AES-GCM-SIV and non-zero IVs
-// 4 - introduction of v2 authentication protocol to prevent reply attacks
+// 4 - introduction of v2 authentication protocol to prevent replay attacks
 // 5 - add key rotation information to the serialised mix packet
 // 6 - support for 'upgrade mode'
 pub const INITIAL_PROTOCOL_VERSION: GatewayProtocolVersion = 1;

common/gateway-requests/src/registration/handshake/client.rs

@@ -5,7 +5,7 @@ use crate::registration::handshake::messages::{Finalization, GatewayMaterialExch
 use crate::registration::handshake::state::State;
 use crate::registration::handshake::HandshakeResult;
 use crate::registration::handshake::{error::HandshakeError, WsItem};
-use crate::{GatewayProtocolVersionExt, INITIAL_PROTOCOL_VERSION};
+use crate::GatewayProtocolVersionExt;
 use futures::{Sink, Stream};
 use rand::{CryptoRng, RngCore};
 use tracing::info;
@@ -18,11 +18,11 @@ impl<S, R> State<'_, S, R> {
         R: CryptoRng + RngCore,
     {
         // 1. if we're using non-legacy, i.e. aes256gcm-siv derivation, generate initiator salt for kdf
-        let maybe_hkdf_salt = self.maybe_generate_initiator_salt();
+        let hkdf_salt = self.generate_initiator_salt();
 
         // 1. send ed25519 pubkey alongside ephemeral x25519 pubkey and a hkdf salt if we're using non-legacy client
-        // LOCAL_ID_PUBKEY || EPHEMERAL_KEY || MAYBE_SALT
-        let init_message = self.init_message(maybe_hkdf_salt.clone());
+        // LOCAL_ID_PUBKEY || EPHEMERAL_KEY || SALT
+        let init_message = self.init_message(hkdf_salt.clone());
         self.send_handshake_data(init_message).await?;
 
         // 2. wait for response with remote x25519 pubkey as well as encrypted signature
@@ -33,23 +33,20 @@ impl<S, R> State<'_, S, R> {
 
         // NEGOTIATE PROTOCOL
         if gateway_protocol.is_future_version() {
-            // SAFETY: future version means it's greater than CURRENT, which is always a `Some`
-            #[allow(clippy::unwrap_used)]
             return Err(HandshakeError::UnsupportedProtocol {
-                version: gateway_protocol.unwrap(),
+                version: gateway_protocol,
             });
         }
-        let gateway_protocol = gateway_protocol.unwrap_or(INITIAL_PROTOCOL_VERSION);
 
         // that should never happen, but we're fine with that outcome
-        if Some(gateway_protocol) != self.proposed_protocol_version() {
+        if gateway_protocol != self.proposed_protocol_version() {
             info!("the gateway insists on protocol version different from the one we suggested. it wants {gateway_protocol} whilst we wanted {:?}, however, we can support it", self.proposed_protocol_version());
             self.set_protocol_version(gateway_protocol);
         }
 
         // 3. derive shared keys locally
         // hkdf::<blake3>::(g^xy)
-        self.derive_shared_key(&mid_res.ephemeral_dh, maybe_hkdf_salt.as_deref());
+        self.derive_shared_key(&mid_res.ephemeral_dh, &hkdf_salt);
 
         // 4. verify the received signature using the locally derived keys
         self.verify_remote_key_material(&mid_res.materials, &mid_res.ephemeral_dh)?;

common/gateway-requests/src/registration/handshake/gateway.rs

@@ -56,10 +56,7 @@ impl<S, R> State<'_, S, R> {
 
         // 2. derive shared keys locally
         // hkdf::<blake3>::(g^xy)
-        self.derive_shared_key(
-            &init_message.ephemeral_dh,
-            init_message.initiator_salt.as_deref(),
-        );
+        self.derive_shared_key(&init_message.ephemeral_dh, &init_message.initiator_salt);
 
         // 3. send ephemeral x25519 pubkey alongside the encrypted signature
         // g^y || AES(k, sig(gate_priv, (g^y || g^x))

common/gateway-requests/src/registration/handshake/messages.rs

@@ -4,7 +4,7 @@
 use crate::registration::handshake::error::HandshakeError;
 use crate::registration::handshake::KDF_SALT_LENGTH;
 use nym_crypto::asymmetric::{ed25519, x25519};
-use nym_crypto::symmetric::aead::{nonce_size, tag_size};
+use nym_crypto::symmetric::aead::{nonce_size, tag_size, Nonce};
 use nym_sphinx::params::GatewayEncryptionAlgorithm;
 
 // it is vital nobody changes the serialisation implementation unless you have an EXTREMELY good reason,
@@ -21,13 +21,13 @@ pub trait HandshakeMessage {
 pub struct Initialisation {
     pub identity: ed25519::PublicKey,
     pub ephemeral_dh: x25519::PublicKey,
-    pub initiator_salt: Option<Vec<u8>>,
+    pub initiator_salt: Vec<u8>,
 }
 
 #[derive(Debug)]
 pub struct MaterialExchange {
     pub signature_ciphertext: Vec<u8>,
-    pub nonce: Option<Vec<u8>>,
+    pub nonce: Nonce<GatewayEncryptionAlgorithm>,
 }
 
 impl MaterialExchange {
@@ -61,21 +61,16 @@ impl Finalization {
 }
 
 impl HandshakeMessage for Initialisation {
-    // LOCAL_ID_PUBKEY || EPHEMERAL_KEY || MAYBE_SALT
+    // LOCAL_ID_PUBKEY || EPHEMERAL_KEY || SALT
     // Eventually the ID_PUBKEY prefix will get removed and recipient will know
     // initializer's identity from another source.
     fn into_bytes(self) -> Vec<u8> {
-        let bytes = self
-            .identity
+        self.identity
             .to_bytes()
             .into_iter()
-            .chain(self.ephemeral_dh.to_bytes());
-
-        if let Some(salt) = self.initiator_salt {
-            bytes.chain(salt).collect()
-        } else {
-            bytes.collect()
-        }
+            .chain(self.ephemeral_dh.to_bytes())
+            .chain(self.initiator_salt)
+            .collect()
     }
 
     // this will need to be adjusted when REMOTE_ID_PUBKEY is removed
@@ -83,9 +78,8 @@ impl HandshakeMessage for Initialisation {
     where
         Self: Sized,
     {
-        let legacy_len = ed25519::PUBLIC_KEY_LENGTH + x25519::PUBLIC_KEY_SIZE;
-        let current_len = legacy_len + KDF_SALT_LENGTH;
-        if bytes.len() != legacy_len && bytes.len() != current_len {
+        let current_len = ed25519::PUBLIC_KEY_LENGTH + x25519::PUBLIC_KEY_SIZE + KDF_SALT_LENGTH;
+        if bytes.len() != current_len {
             return Err(HandshakeError::MalformedRequest);
         }
 
@@ -95,14 +89,13 @@ impl HandshakeMessage for Initialisation {
         // SAFETY: this can only fail if the provided bytes have len different from encryption::PUBLIC_KEY_SIZE
         // which is impossible
         #[allow(clippy::unwrap_used)]
-        let ephemeral_dh =
-            x25519::PublicKey::from_bytes(&bytes[ed25519::PUBLIC_KEY_LENGTH..legacy_len]).unwrap();
+        let ephemeral_dh = x25519::PublicKey::from_bytes(
+            &bytes
+                [ed25519::PUBLIC_KEY_LENGTH..ed25519::PUBLIC_KEY_LENGTH + x25519::PUBLIC_KEY_SIZE],
+        )
+        .unwrap();
 
-        let initiator_salt = if bytes.len() == legacy_len {
-            None
-        } else {
-            Some(bytes[legacy_len..].to_vec())
-        };
+        let initiator_salt = bytes[ed25519::PUBLIC_KEY_LENGTH + x25519::PUBLIC_KEY_SIZE..].to_vec();
 
         Ok(Initialisation {
             identity,
@@ -115,43 +108,31 @@ impl HandshakeMessage for Initialisation {
 impl HandshakeMessage for MaterialExchange {
     // AES(k, SIG(PRIV_GATE, G^y || G^x))
     fn into_bytes(self) -> Vec<u8> {
-        if let Some(nonce) = self.nonce {
-            self.signature_ciphertext
-                .iter()
-                .cloned()
-                .chain(nonce)
-                .collect()
-        } else {
-            self.signature_ciphertext.to_vec()
-        }
+        self.signature_ciphertext
+            .iter()
+            .cloned()
+            .chain(self.nonce)
+            .collect()
     }
 
     fn try_from_bytes(bytes: &[u8]) -> Result<Self, HandshakeError>
     where
         Self: Sized,
     {
-        // we expect to receive either:
-        // LEGACY: ed25519 signature ciphertext (64 bytes)
         // CURRENT: ed25519 signature ciphertext (+ tag) + AES256-GCM-SIV nonce (76 bytes)
-        let legacy_len = ed25519::SIGNATURE_LENGTH;
-        let current_len = legacy_len
+        let current_len = ed25519::SIGNATURE_LENGTH
             + tag_size::<GatewayEncryptionAlgorithm>()
             + nonce_size::<GatewayEncryptionAlgorithm>();
 
-        if bytes.len() != legacy_len && bytes.len() != current_len {
+        if bytes.len() != current_len {
             return Err(HandshakeError::MalformedResponse);
         }
 
-        let (signature_ciphertext, nonce) = if bytes.len() == current_len {
-            let ciphertext_len =
-                ed25519::SIGNATURE_LENGTH + tag_size::<GatewayEncryptionAlgorithm>();
-            (
-                bytes[..ciphertext_len].to_vec(),
-                Some(bytes[ciphertext_len..].to_vec()),
-            )
-        } else {
-            (bytes.to_vec(), None)
-        };
+        let ciphertext_len = ed25519::SIGNATURE_LENGTH + tag_size::<GatewayEncryptionAlgorithm>();
+        let signature_ciphertext = bytes[..ciphertext_len].to_vec();
+
+        // SAFETY: we know the bytes have correct length
+        let nonce = Nonce::<GatewayEncryptionAlgorithm>::clone_from_slice(&bytes[ciphertext_len..]);
 
         Ok(MaterialExchange {
             signature_ciphertext,

common/gateway-requests/src/registration/handshake/mod.rs

@@ -3,7 +3,7 @@
 
 use self::error::HandshakeError;
 use crate::registration::handshake::state::State;
-use crate::{GatewayProtocolVersion, SharedGatewayKey};
+use crate::{GatewayProtocolVersion, SharedSymmetricKey};
 use futures::future::BoxFuture;
 use futures::{Sink, Stream};
 use nym_crypto::asymmetric::ed25519;
@@ -48,7 +48,7 @@ impl Future for GatewayHandshake<'_> {
 #[derive(Debug, PartialEq)]
 pub struct HandshakeResult {
     pub negotiated_protocol: GatewayProtocolVersion,
-    pub derived_key: SharedGatewayKey,
+    pub derived_key: SharedSymmetricKey,
 }
 
 pub fn client_handshake<'a, S, R>(
@@ -56,7 +56,7 @@ pub fn client_handshake<'a, S, R>(
     ws_stream: &'a mut S,
     identity: &'a ed25519::KeyPair,
     gateway_pubkey: ed25519::PublicKey,
-    gateway_protocol: Option<GatewayProtocolVersion>,
+    gateway_protocol: GatewayProtocolVersion,
     #[cfg(not(target_arch = "wasm32"))] shutdown_token: ShutdownToken,
 ) -> GatewayHandshake<'a>
 where
@@ -84,7 +84,7 @@ pub fn gateway_handshake<'a, S, R>(
     ws_stream: &'a mut S,
     identity: &'a ed25519::KeyPair,
     received_init_payload: Vec<u8>,
-    requested_client_protocol: Option<GatewayProtocolVersion>,
+    requested_client_protocol: GatewayProtocolVersion,
     shutdown_token: ShutdownToken,
 ) -> GatewayHandshake<'a>
 where
@@ -125,7 +125,7 @@ DONE(status)
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::{ClientControlRequest, CURRENT_PROTOCOL_VERSION, INITIAL_PROTOCOL_VERSION};
+    use crate::{ClientControlRequest, CURRENT_PROTOCOL_VERSION};
     use anyhow::{bail, Context};
     use futures::StreamExt;
     use nym_test_utils::helpers::u64_seeded_rng;
@@ -221,7 +221,7 @@ mod tests {
             client.socket,
             client.keys,
             *gateway.keys.public_key(),
-            Some(CURRENT_PROTOCOL_VERSION),
+            CURRENT_PROTOCOL_VERSION,
             ShutdownToken::default(),
         );
 
@@ -235,7 +235,7 @@ mod tests {
             gateway.socket,
             gateway.keys,
             init_msg,
-            Some(CURRENT_PROTOCOL_VERSION),
+            CURRENT_PROTOCOL_VERSION,
             ShutdownToken::default(),
         );
 
@@ -261,7 +261,7 @@ mod tests {
             client.socket,
             client.keys,
             *gateway.keys.public_key(),
-            Some(CURRENT_PROTOCOL_VERSION + 42),
+            CURRENT_PROTOCOL_VERSION + 42,
             ShutdownToken::default(),
         );
 
@@ -274,7 +274,7 @@ mod tests {
             gateway.socket,
             gateway.keys,
             init_msg,
-            Some(CURRENT_PROTOCOL_VERSION + 42),
+            CURRENT_PROTOCOL_VERSION + 42,
             ShutdownToken::default(),
         );
 
@@ -292,46 +292,4 @@ mod tests {
 
         Ok(())
     }
-
-    #[tokio::test]
-    async fn protocol_upgrade() -> anyhow::Result<()> {
-        let (client, gateway) = setup();
-
-        let handshake_client = client_handshake(
-            client.rng,
-            client.socket,
-            client.keys,
-            *gateway.keys.public_key(),
-            None,
-            ShutdownToken::default(),
-        );
-
-        let client_fut = handshake_client.spawn_timeboxed();
-
-        // we need to receive the first message so that it could be propagated to the gateway side of the handshake
-        let init_msg = gateway.socket.get_handshake_init_data().await?;
-
-        let handshake_gateway = gateway_handshake(
-            gateway.rng,
-            gateway.socket,
-            gateway.keys,
-            init_msg,
-            None,
-            ShutdownToken::default(),
-        );
-
-        let gateway_fut = handshake_gateway.spawn_timeboxed();
-        let (client, gateway) = join!(client_fut, gateway_fut);
-
-        let client_res = client???;
-        let gateway_res = gateway???;
-
-        // ensure the created keys are the same
-        assert_eq!(client_res, gateway_res);
-
-        // and the protocol got upgraded to the first known version
-        assert_eq!(client_res.negotiated_protocol, INITIAL_PROTOCOL_VERSION);
-
-        Ok(())
-    }
 }

common/gateway-requests/src/registration/handshake/state.rs

@@ -5,12 +5,11 @@ use crate::registration::handshake::error::HandshakeError;
 use crate::registration::handshake::messages::{
     HandshakeMessage, Initialisation, MaterialExchange,
 };
-use crate::registration::handshake::{HandshakeResult, SharedGatewayKey, WsItem, KDF_SALT_LENGTH};
-use crate::shared_key::SharedKeySize;
-use crate::{
-    types, GatewayProtocolVersion, GatewayProtocolVersionExt, LegacySharedKeySize,
-    LegacySharedKeys, SharedSymmetricKey, INITIAL_PROTOCOL_VERSION,
+use crate::registration::handshake::{
+    HandshakeResult, SharedSymmetricKey, WsItem, KDF_SALT_LENGTH,
 };
+use crate::shared_key::SharedKeySize;
+use crate::{types, GatewayProtocolVersion};
 use futures::{Sink, SinkExt, Stream, StreamExt};
 use nym_crypto::asymmetric::{ed25519, x25519};
 use nym_crypto::symmetric::aead::random_nonce;
@@ -48,17 +47,15 @@ pub(crate) struct State<'a, S, R> {
     ephemeral_keypair: x25519::KeyPair,
 
     /// The derived shared key using the ephemeral keys of both parties.
-    derived_shared_keys: Option<SharedGatewayKey>,
+    derived_shared_keys: Option<SharedSymmetricKey>,
 
     /// The known or received public identity key of the remote.
     /// Ideally it would always be known before the handshake was initiated.
     remote_pubkey: Option<ed25519::PublicKey>,
 
     /// Version of the protocol to use during the handshake that also implicitly specifies
-    /// additional features such as the type of derived shared keys, i.e.
-    /// AES128Ctr + blake3 HMAC keys (legacy) or AES256-GCM-SIV (current)
-    /// the above is decided by whether the specified protocol version supports the new variant or not.
-    protocol_version: Option<GatewayProtocolVersion>,
+    /// additional features
+    protocol_version: GatewayProtocolVersion,
 
     // channel to receive shutdown signal
     #[cfg(not(target_arch = "wasm32"))]
@@ -71,7 +68,7 @@ impl<'a, S, R> State<'a, S, R> {
         ws_stream: &'a mut S,
         identity: &'a ed25519::KeyPair,
         remote_pubkey: Option<ed25519::PublicKey>,
-        protocol_version: Option<GatewayProtocolVersion>,
+        protocol_version: GatewayProtocolVersion,
         #[cfg(not(target_arch = "wasm32"))] shutdown_token: ShutdownToken,
     ) -> Self
     where
@@ -96,31 +93,27 @@ impl<'a, S, R> State<'a, S, R> {
         self.ephemeral_keypair.public_key()
     }
 
-    pub(crate) fn proposed_protocol_version(&self) -> Option<GatewayProtocolVersion> {
+    pub(crate) fn proposed_protocol_version(&self) -> GatewayProtocolVersion {
         self.protocol_version
     }
 
     pub(crate) fn set_protocol_version(&mut self, protocol_version: GatewayProtocolVersion) {
-        self.protocol_version = Some(protocol_version);
+        self.protocol_version = protocol_version;
     }
 
-    pub(crate) fn maybe_generate_initiator_salt(&mut self) -> Option<Vec<u8>>
+    pub(crate) fn generate_initiator_salt(&mut self) -> Vec<u8>
     where
         R: CryptoRng + RngCore,
     {
-        if self.protocol_version.supports_aes256_gcm_siv() {
-            let mut salt = vec![0u8; KDF_SALT_LENGTH];
-            self.rng.fill_bytes(&mut salt);
-            Some(salt)
-        } else {
-            None
-        }
+        let mut salt = vec![0u8; KDF_SALT_LENGTH];
+        self.rng.fill_bytes(&mut salt);
+        salt
     }
 
-    // LOCAL_ID_PUBKEY || EPHEMERAL_KEY || MAYBE_SALT
+    // LOCAL_ID_PUBKEY || EPHEMERAL_KEY || SALT
     // Eventually the ID_PUBKEY prefix will get removed and recipient will know
     // initializer's identity from another source.
-    pub(crate) fn init_message(&self, initiator_salt: Option<Vec<u8>>) -> Initialisation {
+    pub(crate) fn init_message(&self, initiator_salt: Vec<u8>) -> Initialisation {
         Initialisation {
             identity: *self.identity.public_key(),
             ephemeral_dh: *self.ephemeral_keypair.public_key(),
@@ -138,23 +131,19 @@ impl<'a, S, R> State<'a, S, R> {
     pub(crate) fn derive_shared_key(
         &mut self,
         remote_ephemeral_key: &x25519::PublicKey,
-        initiator_salt: Option<&[u8]>,
+        initiator_salt: &[u8],
     ) {
         let dh_result = self
             .ephemeral_keypair
             .private_key()
             .diffie_hellman(remote_ephemeral_key);
 
-        let key_size = if self.protocol_version.supports_aes256_gcm_siv() {
-            SharedKeySize::to_usize()
-        } else {
-            LegacySharedKeySize::to_usize()
-        };
+        let key_size = SharedKeySize::to_usize();
 
         // SAFETY: there is no reason for this to fail as our okm is expected to be only 16 bytes
         #[allow(clippy::expect_used)]
         let okm = hkdf::extract_then_expand::<GatewaySharedKeyHkdfAlgorithm>(
-            initiator_salt,
+            Some(initiator_salt),
             &dh_result,
             None,
             key_size,
@@ -162,17 +151,10 @@ impl<'a, S, R> State<'a, S, R> {
         .expect("somehow too long okm was provided");
 
         // SAFETY: the okm has been expanded to the length expected by the corresponding keys
-        let shared_key = if self.protocol_version.supports_aes256_gcm_siv() {
-            #[allow(clippy::expect_used)]
-            let current_key = SharedSymmetricKey::try_from_bytes(&okm)
-                .expect("okm was expanded to incorrect length!");
-            SharedGatewayKey::Current(current_key)
-        } else {
-            #[allow(clippy::expect_used)]
-            let legacy_key = LegacySharedKeys::try_from_bytes(&okm)
-                .expect("okm was expanded to incorrect length!");
-            SharedGatewayKey::Legacy(legacy_key)
-        };
+        #[allow(clippy::expect_used)]
+        let shared_key = SharedSymmetricKey::try_from_bytes(&okm)
+            .expect("okm was expanded to incorrect length!");
+
         self.derived_shared_keys = Some(shared_key)
     }
 
@@ -191,12 +173,8 @@ impl<'a, S, R> State<'a, S, R> {
             .collect();
         let signature = self.identity.private_key().sign(plaintext);
 
-        let nonce = if self.protocol_version.supports_aes256_gcm_siv() {
-            let mut rng = thread_rng();
-            Some(random_nonce::<GatewayEncryptionAlgorithm, _>(&mut rng).to_vec())
-        } else {
-            None
-        };
+        let mut rng = thread_rng();
+        let nonce = random_nonce::<GatewayEncryptionAlgorithm, _>(&mut rng);
 
         // SAFETY: this function is only called after the local key has already been derived
         #[allow(clippy::expect_used)]
@@ -204,7 +182,7 @@ impl<'a, S, R> State<'a, S, R> {
             .derived_shared_keys
             .as_ref()
             .expect("shared key was not derived!")
-            .encrypt_naive(&signature.to_bytes(), nonce.as_deref())?;
+            .encrypt(&signature.to_bytes(), &nonce)?;
 
         Ok(MaterialExchange {
             signature_ciphertext,
@@ -224,15 +202,10 @@ impl<'a, S, R> State<'a, S, R> {
             .as_ref()
             .expect("shared key was not derived!");
 
-        // if the [client] init message contained non-legacy flag, the associated nonce MUST be present
-        if self.protocol_version.supports_aes256_gcm_siv() && remote_response.nonce.is_none() {
-            return Err(HandshakeError::MissingNonceForCurrentKey);
-        }
-
         // first decrypt received data
-        let decrypted_signature = derived_shared_key.decrypt_naive(
+        let decrypted_signature = derived_shared_key.decrypt(
             &remote_response.signature_ciphertext,
-            remote_response.nonce.as_deref(),
+            &remote_response.nonce,
         )?;
 
         // now verify signature itself
@@ -262,7 +235,7 @@ impl<'a, S, R> State<'a, S, R> {
     #[allow(clippy::complexity)]
     fn on_wg_msg(
         msg: Option<WsItem>,
-    ) -> Result<Option<(Vec<u8>, Option<GatewayProtocolVersion>)>, HandshakeError> {
+    ) -> Result<Option<(Vec<u8>, GatewayProtocolVersion)>, HandshakeError> {
         let Some(msg) = msg else {
             return Err(HandshakeError::ClosedStream);
         };
@@ -303,7 +276,7 @@ impl<'a, S, R> State<'a, S, R> {
     #[cfg(not(target_arch = "wasm32"))]
     async fn _receive_handshake_message_bytes(
         &mut self,
-    ) -> Result<(Vec<u8>, Option<GatewayProtocolVersion>), HandshakeError>
+    ) -> Result<(Vec<u8>, GatewayProtocolVersion), HandshakeError>
     where
         S: Stream<Item = WsItem> + Unpin,
     {
@@ -324,7 +297,7 @@ impl<'a, S, R> State<'a, S, R> {
     #[cfg(target_arch = "wasm32")]
     async fn _receive_handshake_message_bytes(
         &mut self,
-    ) -> Result<(Vec<u8>, Option<GatewayProtocolVersion>), HandshakeError>
+    ) -> Result<(Vec<u8>, GatewayProtocolVersion), HandshakeError>
     where
         S: Stream<Item = WsItem> + Unpin,
     {
@@ -339,7 +312,7 @@ impl<'a, S, R> State<'a, S, R> {
 
     pub(crate) async fn receive_handshake_message<M>(
         &mut self,
-    ) -> Result<(M, Option<GatewayProtocolVersion>), HandshakeError>
+    ) -> Result<(M, GatewayProtocolVersion), HandshakeError>
     where
         S: Stream<Item = WsItem> + Unpin,
         M: HandshakeMessage,
@@ -396,9 +369,7 @@ impl<'a, S, R> State<'a, S, R> {
         // SAFETY: handshake can't be finalised without deriving the shared keys
         #[allow(clippy::unwrap_used)]
         HandshakeResult {
-            negotiated_protocol: self
-                .proposed_protocol_version()
-                .unwrap_or(INITIAL_PROTOCOL_VERSION),
+            negotiated_protocol: self.proposed_protocol_version(),
             derived_key: self.derived_shared_keys.unwrap(),
         }
     }

common/gateway-requests/src/shared_key.rs

@@ -0,0 +1,141 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_crypto::blake3;
+use nym_crypto::crypto_hash::compute_digest;
+use nym_crypto::generic_array::{typenum::Unsigned, GenericArray};
+use nym_crypto::symmetric::aead::{
+    self, nonce_size, random_nonce, AeadError, AeadKey, KeySizeUser, Nonce,
+};
+use nym_pemstore::traits::PemStorableKey;
+use nym_sphinx::params::GatewayEncryptionAlgorithm;
+use rand::thread_rng;
+use serde::{Deserialize, Serialize};
+use thiserror::Error;
+use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};
+
+pub type SharedKeySize = <GatewayEncryptionAlgorithm as KeySizeUser>::KeySize;
+
+#[derive(Debug, Error)]
+pub enum SharedKeyUsageError {
+    #[error("the request is too short")]
+    TooShortRequest,
+
+    #[error("provided MAC is invalid")]
+    InvalidMac,
+
+    #[error("the provided nonce (or legacy IV) did not have the expected length")]
+    MalformedNonce,
+
+    #[error("did not provide a valid nonce for aead encryption")]
+    MissingAeadNonce,
+
+    #[error("failed to either encrypt or decrypt provided message")]
+    AeadFailure(#[from] AeadError),
+}
+
+#[derive(Debug, PartialEq, Serialize, Deserialize, Zeroize, ZeroizeOnDrop)]
+pub struct SharedSymmetricKey(AeadKey<GatewayEncryptionAlgorithm>);
+
+type KeySize = <GatewayEncryptionAlgorithm as KeySizeUser>::KeySize;
+
+#[derive(Debug, Clone, Copy, Error)]
+pub enum SharedKeyConversionError {
+    #[error("the string representation of the shared key was malformed: {0}")]
+    DecodeError(#[from] bs58::decode::Error),
+    #[error(
+        "the received shared keys had invalid size. Got: {received}, but expected: {expected}"
+    )]
+    InvalidSharedKeysSize { received: usize, expected: usize },
+}
+
+impl SharedSymmetricKey {
+    pub fn random_nonce(&self) -> Nonce<GatewayEncryptionAlgorithm> {
+        let mut rng = thread_rng();
+        random_nonce::<GatewayEncryptionAlgorithm, _>(&mut rng)
+    }
+
+    pub fn nonce_size(&self) -> usize {
+        nonce_size::<GatewayEncryptionAlgorithm>()
+    }
+
+    pub fn validate_aead_nonce(
+        raw: &[u8],
+    ) -> Result<Nonce<GatewayEncryptionAlgorithm>, SharedKeyUsageError> {
+        if raw.len() != nonce_size::<GatewayEncryptionAlgorithm>() {
+            return Err(SharedKeyUsageError::MalformedNonce);
+        }
+        Ok(Nonce::<GatewayEncryptionAlgorithm>::clone_from_slice(raw))
+    }
+    pub fn try_from_bytes(bytes: &[u8]) -> Result<Self, SharedKeyConversionError> {
+        if bytes.len() != KeySize::to_usize() {
+            return Err(SharedKeyConversionError::InvalidSharedKeysSize {
+                received: bytes.len(),
+                expected: KeySize::to_usize(),
+            });
+        }
+
+        Ok(SharedSymmetricKey(GenericArray::clone_from_slice(bytes)))
+    }
+
+    pub fn zeroizing_clone(&self) -> Zeroizing<Self> {
+        Zeroizing::new(SharedSymmetricKey(self.0))
+    }
+
+    pub fn digest(&self) -> Vec<u8> {
+        compute_digest::<blake3::Hasher>(self.as_bytes()).to_vec()
+    }
+
+    pub fn as_bytes(&self) -> &[u8] {
+        self.0.as_slice()
+    }
+
+    pub fn to_bytes(&self) -> Vec<u8> {
+        self.0.iter().copied().collect()
+    }
+
+    pub fn try_from_base58_string<S: Into<String>>(
+        val: S,
+    ) -> Result<Self, SharedKeyConversionError> {
+        let bs58_str = Zeroizing::new(val.into());
+        let decoded = Zeroizing::new(bs58::decode(bs58_str).into_vec()?);
+        Self::try_from_bytes(&decoded)
+    }
+
+    pub fn to_base58_string(&self) -> String {
+        let bytes = Zeroizing::new(self.to_bytes());
+        bs58::encode(bytes).into_string()
+    }
+
+    pub fn encrypt(
+        &self,
+        plaintext: &[u8],
+        nonce: &Nonce<GatewayEncryptionAlgorithm>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        aead::encrypt::<GatewayEncryptionAlgorithm>(&self.0, nonce, plaintext).map_err(Into::into)
+    }
+
+    pub fn decrypt(
+        &self,
+        ciphertext: &[u8],
+        nonce: &Nonce<GatewayEncryptionAlgorithm>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        aead::decrypt::<GatewayEncryptionAlgorithm>(&self.0, nonce, ciphertext).map_err(Into::into)
+    }
+}
+
+impl PemStorableKey for SharedSymmetricKey {
+    type Error = SharedKeyConversionError;
+
+    fn pem_type() -> &'static str {
+        "AES-256-GCM-SIV GATEWAY SHARED KEY"
+    }
+
+    fn to_bytes(&self) -> Vec<u8> {
+        self.to_bytes()
+    }
+
+    fn from_bytes(bytes: &[u8]) -> Result<Self, Self::Error> {
+        Self::try_from_bytes(bytes)
+    }
+}

common/gateway-requests/src/shared_key/helpers.rs

@@ -1,98 +0,0 @@
-// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0
-
-use crate::{LegacySharedKeys, SharedGatewayKey, SharedKeyUsageError, SharedSymmetricKey};
-use nym_crypto::symmetric::aead::random_nonce;
-use nym_crypto::symmetric::stream_cipher::random_iv;
-use nym_sphinx::params::{GatewayEncryptionAlgorithm, LegacyGatewayEncryptionAlgorithm};
-use rand::thread_rng;
-
-pub trait SymmetricKey {
-    fn random_nonce_or_iv(&self) -> Vec<u8>;
-
-    fn encrypt(
-        &self,
-        plaintext: &[u8],
-        nonce: Option<&[u8]>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError>;
-
-    fn decrypt(
-        &self,
-        ciphertext: &[u8],
-        nonce: Option<&[u8]>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError>;
-}
-
-impl SymmetricKey for SharedGatewayKey {
-    fn random_nonce_or_iv(&self) -> Vec<u8> {
-        self.random_nonce_or_iv()
-    }
-
-    fn encrypt(
-        &self,
-        plaintext: &[u8],
-        nonce: Option<&[u8]>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError> {
-        self.encrypt(plaintext, nonce)
-    }
-
-    fn decrypt(
-        &self,
-        ciphertext: &[u8],
-        nonce: Option<&[u8]>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError> {
-        self.decrypt(ciphertext, nonce)
-    }
-}
-
-impl SymmetricKey for SharedSymmetricKey {
-    fn random_nonce_or_iv(&self) -> Vec<u8> {
-        let mut rng = thread_rng();
-
-        random_nonce::<GatewayEncryptionAlgorithm, _>(&mut rng).to_vec()
-    }
-
-    fn encrypt(
-        &self,
-        plaintext: &[u8],
-        nonce: Option<&[u8]>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError> {
-        let nonce = SharedGatewayKey::validate_aead_nonce(nonce)?;
-        self.encrypt(plaintext, &nonce)
-    }
-
-    fn decrypt(
-        &self,
-        ciphertext: &[u8],
-        nonce: Option<&[u8]>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError> {
-        let nonce = SharedGatewayKey::validate_aead_nonce(nonce)?;
-        self.decrypt(ciphertext, &nonce)
-    }
-}
-
-impl SymmetricKey for LegacySharedKeys {
-    fn random_nonce_or_iv(&self) -> Vec<u8> {
-        let mut rng = thread_rng();
-
-        random_iv::<LegacyGatewayEncryptionAlgorithm, _>(&mut rng).to_vec()
-    }
-
-    fn encrypt(
-        &self,
-        plaintext: &[u8],
-        nonce: Option<&[u8]>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError> {
-        let iv = SharedGatewayKey::validate_cipher_iv(nonce)?;
-        Ok(self.encrypt_and_tag(plaintext, iv))
-    }
-
-    fn decrypt(
-        &self,
-        ciphertext: &[u8],
-        nonce: Option<&[u8]>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError> {
-        let iv = SharedGatewayKey::validate_cipher_iv(nonce)?;
-        self.decrypt_tagged(ciphertext, iv)
-    }
-}

common/gateway-requests/src/shared_key/legacy.rs

@@ -1,246 +0,0 @@
-// Copyright 2020-2023 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0
-
-use crate::registration::handshake::KDF_SALT_LENGTH;
-use crate::shared_key::SharedSymmetricKey;
-use crate::shared_key::{SharedKeyConversionError, SharedKeySize, SharedKeyUsageError};
-use crate::LegacyGatewayMacSize;
-use nym_crypto::generic_array::{
-    typenum::{Sum, Unsigned, U16},
-    GenericArray,
-};
-use nym_crypto::hkdf;
-use nym_crypto::hmac::{compute_keyed_hmac, recompute_keyed_hmac_and_verify_tag};
-use nym_crypto::symmetric::stream_cipher::{self, CipherKey, KeySizeUser, IV};
-use nym_pemstore::traits::PemStorableKey;
-use nym_sphinx::params::{
-    GatewayIntegrityHmacAlgorithm, GatewaySharedKeyHkdfAlgorithm, LegacyGatewayEncryptionAlgorithm,
-};
-use rand::{thread_rng, RngCore};
-use serde::{Deserialize, Serialize};
-use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};
-
-// shared key is as long as the encryption key and the MAC key combined.
-pub type LegacySharedKeySize = Sum<EncryptionKeySize, MacKeySize>;
-
-// we're using 16 byte long key in sphinx, so let's use the same one here
-type MacKeySize = U16;
-type EncryptionKeySize = <LegacyGatewayEncryptionAlgorithm as KeySizeUser>::KeySize;
-
-/// Shared key used when computing MAC for messages exchanged between client and its gateway.
-pub type MacKey = GenericArray<u8, MacKeySize>;
-
-#[derive(Debug, PartialEq, Serialize, Deserialize, Zeroize, ZeroizeOnDrop)]
-pub struct LegacySharedKeys {
-    encryption_key: CipherKey<LegacyGatewayEncryptionAlgorithm>,
-    mac_key: MacKey,
-}
-
-impl LegacySharedKeys {
-    pub fn upgrade(&self) -> (SharedSymmetricKey, Vec<u8>) {
-        let mut rng = thread_rng();
-        let mut salt = vec![0u8; KDF_SALT_LENGTH];
-        rng.fill_bytes(&mut salt);
-
-        let legacy_bytes = Zeroizing::new(self.to_bytes());
-        #[allow(clippy::expect_used)]
-        let okm = hkdf::extract_then_expand::<GatewaySharedKeyHkdfAlgorithm>(
-            Some(&salt),
-            &legacy_bytes,
-            None,
-            SharedKeySize::to_usize(),
-        )
-        .expect("somehow too long okm was provided");
-
-        #[allow(clippy::expect_used)]
-        let key = SharedSymmetricKey::try_from_bytes(&okm)
-            .expect("okm was expanded to incorrect length!");
-        (key, salt)
-    }
-
-    pub fn upgrade_verify(
-        &self,
-        salt: &[u8],
-        expected_digest: &[u8],
-    ) -> Option<SharedSymmetricKey> {
-        let legacy_bytes = Zeroizing::new(self.to_bytes());
-        #[allow(clippy::expect_used)]
-        let okm = hkdf::extract_then_expand::<GatewaySharedKeyHkdfAlgorithm>(
-            Some(salt),
-            &legacy_bytes,
-            None,
-            SharedKeySize::to_usize(),
-        )
-        .expect("somehow too long okm was provided");
-
-        #[allow(clippy::expect_used)]
-        let key = SharedSymmetricKey::try_from_bytes(&okm)
-            .expect("okm was expanded to incorrect length!");
-        if key.digest() != expected_digest {
-            // no need to zeroize  that key since it's malformed and we won't be using it anyway
-            None
-        } else {
-            Some(key)
-        }
-    }
-
-    pub fn try_from_bytes(bytes: &[u8]) -> Result<Self, SharedKeyConversionError> {
-        if bytes.len() != LegacySharedKeySize::to_usize() {
-            return Err(SharedKeyConversionError::InvalidSharedKeysSize {
-                received: bytes.len(),
-                expected: LegacySharedKeySize::to_usize(),
-            });
-        }
-
-        let encryption_key =
-            GenericArray::clone_from_slice(&bytes[..EncryptionKeySize::to_usize()]);
-        let mac_key = GenericArray::clone_from_slice(&bytes[EncryptionKeySize::to_usize()..]);
-
-        Ok(LegacySharedKeys {
-            encryption_key,
-            mac_key,
-        })
-    }
-
-    /// Encrypts the provided data using the optionally provided initialisation vector,
-    /// or a 0 value if nothing was given.
-    /// It does **NOT** attach any integrity macs on the produced ciphertext
-    pub fn encrypt_without_tagging(
-        &self,
-        data: &[u8],
-        iv: Option<&IV<LegacyGatewayEncryptionAlgorithm>>,
-    ) -> Vec<u8> {
-        match iv {
-            Some(iv) => stream_cipher::encrypt::<LegacyGatewayEncryptionAlgorithm>(
-                self.encryption_key(),
-                iv,
-                data,
-            ),
-            None => {
-                let zero_iv = stream_cipher::zero_iv::<LegacyGatewayEncryptionAlgorithm>();
-                stream_cipher::encrypt::<LegacyGatewayEncryptionAlgorithm>(
-                    self.encryption_key(),
-                    &zero_iv,
-                    data,
-                )
-            }
-        }
-    }
-
-    /// Encrypts the provided data using the optionally provided initialisation vector,
-    /// or a 0 value if nothing was given. Then it computes an integrity mac and concatenates it
-    /// with the previously produced ciphertext.
-    pub fn encrypt_and_tag(
-        &self,
-        data: &[u8],
-        iv: Option<&IV<LegacyGatewayEncryptionAlgorithm>>,
-    ) -> Vec<u8> {
-        let ciphertext = self.encrypt_without_tagging(data, iv);
-        let mac = compute_keyed_hmac::<GatewayIntegrityHmacAlgorithm>(
-            self.mac_key().as_slice(),
-            &ciphertext,
-        );
-
-        mac.into_bytes().into_iter().chain(ciphertext).collect()
-    }
-
-    pub fn decrypt_without_tag(
-        &self,
-        ciphertext: &[u8],
-        iv: Option<&IV<LegacyGatewayEncryptionAlgorithm>>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError> {
-        let zero_iv = stream_cipher::zero_iv::<LegacyGatewayEncryptionAlgorithm>();
-        let iv = iv.unwrap_or(&zero_iv);
-        Ok(stream_cipher::decrypt::<LegacyGatewayEncryptionAlgorithm>(
-            self.encryption_key(),
-            iv,
-            ciphertext,
-        ))
-    }
-
-    pub fn decrypt_tagged(
-        &self,
-        enc_data: &[u8],
-        iv: Option<&IV<LegacyGatewayEncryptionAlgorithm>>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError> {
-        let mac_size = LegacyGatewayMacSize::to_usize();
-        if enc_data.len() < mac_size {
-            return Err(SharedKeyUsageError::TooShortRequest);
-        }
-
-        let mac_tag = &enc_data[..mac_size];
-        let message_bytes = &enc_data[mac_size..];
-
-        if !recompute_keyed_hmac_and_verify_tag::<GatewayIntegrityHmacAlgorithm>(
-            self.mac_key().as_slice(),
-            message_bytes,
-            mac_tag,
-        ) {
-            return Err(SharedKeyUsageError::InvalidMac);
-        }
-
-        // couldn't have made the first borrow mutable as you can't have an immutable borrow
-        // together with a mutable one
-        let mut message_bytes_mut = message_bytes.to_vec();
-
-        let zero_iv = stream_cipher::zero_iv::<LegacyGatewayEncryptionAlgorithm>();
-        let iv = iv.unwrap_or(&zero_iv);
-        stream_cipher::decrypt_in_place::<LegacyGatewayEncryptionAlgorithm>(
-            self.encryption_key(),
-            iv,
-            &mut message_bytes_mut,
-        );
-        Ok(message_bytes_mut)
-    }
-
-    pub fn encryption_key(&self) -> &CipherKey<LegacyGatewayEncryptionAlgorithm> {
-        &self.encryption_key
-    }
-
-    pub fn mac_key(&self) -> &MacKey {
-        &self.mac_key
-    }
-
-    pub fn to_bytes(&self) -> Vec<u8> {
-        self.encryption_key
-            .iter()
-            .copied()
-            .chain(self.mac_key.iter().copied())
-            .collect()
-    }
-
-    pub fn try_from_base58_string<S: Into<String>>(
-        val: S,
-    ) -> Result<Self, SharedKeyConversionError> {
-        let decoded = bs58::decode(val.into()).into_vec()?;
-        LegacySharedKeys::try_from_bytes(&decoded)
-    }
-
-    pub fn to_base58_string(&self) -> String {
-        bs58::encode(self.to_bytes()).into_string()
-    }
-}
-
-impl From<LegacySharedKeys> for String {
-    fn from(keys: LegacySharedKeys) -> Self {
-        keys.to_base58_string()
-    }
-}
-
-impl PemStorableKey for LegacySharedKeys {
-    type Error = SharedKeyConversionError;
-
-    fn pem_type() -> &'static str {
-        // TODO: If common\nymsphinx\params\src\lib::GatewayIntegrityHmacAlgorithm changes
-        // the pem type needs updating!
-        "AES-128-CTR + HMAC-BLAKE3 GATEWAY SHARED KEYS"
-    }
-
-    fn to_bytes(&self) -> Vec<u8> {
-        self.to_bytes()
-    }
-
-    fn from_bytes(bytes: &[u8]) -> Result<Self, Self::Error> {
-        Self::try_from_bytes(bytes)
-    }
-}

common/gateway-requests/src/shared_key/mod.rs

@@ -1,306 +0,0 @@
-// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0
-
-use nym_crypto::blake3;
-use nym_crypto::crypto_hash::compute_digest;
-use nym_crypto::generic_array::{typenum::Unsigned, GenericArray};
-use nym_crypto::symmetric::aead::{
-    self, nonce_size, random_nonce, AeadError, AeadKey, KeySizeUser, Nonce,
-};
-use nym_crypto::symmetric::stream_cipher::{iv_size, random_iv, IV};
-use nym_pemstore::traits::PemStorableKey;
-use nym_sphinx::params::{GatewayEncryptionAlgorithm, LegacyGatewayEncryptionAlgorithm};
-use rand::thread_rng;
-use serde::{Deserialize, Serialize};
-use thiserror::Error;
-use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};
-
-pub use legacy::LegacySharedKeys;
-
-pub mod helpers;
-pub mod legacy;
-
-pub type SharedKeySize = <GatewayEncryptionAlgorithm as KeySizeUser>::KeySize;
-
-#[derive(Debug, PartialEq, Zeroize, ZeroizeOnDrop)]
-pub enum SharedGatewayKey {
-    Current(SharedSymmetricKey),
-    Legacy(LegacySharedKeys),
-}
-
-impl SharedGatewayKey {
-    pub fn is_legacy(&self) -> bool {
-        matches!(self, SharedGatewayKey::Legacy(..))
-    }
-
-    pub fn aes128_ctr_hmac_bs58(&self) -> Option<Zeroizing<String>> {
-        match self {
-            SharedGatewayKey::Current(_) => None,
-            SharedGatewayKey::Legacy(key) => Some(Zeroizing::new(key.to_base58_string())),
-        }
-    }
-
-    pub fn aes256_gcm_siv(&self) -> Option<Zeroizing<Vec<u8>>> {
-        match self {
-            SharedGatewayKey::Current(key) => Some(Zeroizing::new(key.to_bytes())),
-            SharedGatewayKey::Legacy(_) => None,
-        }
-    }
-
-    // it is responsibility of the caller to ensure the correct variant is present
-    #[allow(clippy::panic)]
-    pub fn unwrap_legacy(&self) -> &LegacySharedKeys {
-        match self {
-            SharedGatewayKey::Current(_) => panic!("expected legacy key"),
-            SharedGatewayKey::Legacy(key) => key,
-        }
-    }
-
-    pub fn random_nonce_or_iv(&self) -> Vec<u8> {
-        let mut rng = thread_rng();
-
-        if self.is_legacy() {
-            random_iv::<LegacyGatewayEncryptionAlgorithm, _>(&mut rng).to_vec()
-        } else {
-            random_nonce::<GatewayEncryptionAlgorithm, _>(&mut rng).to_vec()
-        }
-    }
-
-    pub fn random_nonce_or_zero_iv(&self) -> Option<Vec<u8>> {
-        if self.is_legacy() {
-            None
-        } else {
-            let mut rng = thread_rng();
-            Some(random_nonce::<GatewayEncryptionAlgorithm, _>(&mut rng).to_vec())
-        }
-    }
-
-    pub fn nonce_size(&self) -> usize {
-        match self {
-            SharedGatewayKey::Current(_) => nonce_size::<GatewayEncryptionAlgorithm>(),
-            SharedGatewayKey::Legacy(_) => iv_size::<LegacyGatewayEncryptionAlgorithm>(),
-        }
-    }
-}
-
-impl From<LegacySharedKeys> for SharedGatewayKey {
-    fn from(keys: LegacySharedKeys) -> Self {
-        SharedGatewayKey::Legacy(keys)
-    }
-}
-
-impl From<SharedSymmetricKey> for SharedGatewayKey {
-    fn from(keys: SharedSymmetricKey) -> Self {
-        SharedGatewayKey::Current(keys)
-    }
-}
-
-#[derive(Debug, Error)]
-pub enum SharedKeyUsageError {
-    #[error("the request is too short")]
-    TooShortRequest,
-
-    #[error("provided MAC is invalid")]
-    InvalidMac,
-
-    #[error("the provided nonce (or legacy IV) did not have the expected length")]
-    MalformedNonce,
-
-    #[error("did not provide a valid nonce for aead encryption")]
-    MissingAeadNonce,
-
-    #[error("failed to either encrypt or decrypt provided message")]
-    AeadFailure(#[from] AeadError),
-}
-
-impl SharedGatewayKey {
-    fn validate_aead_nonce(
-        raw: Option<&[u8]>,
-    ) -> Result<Nonce<GatewayEncryptionAlgorithm>, SharedKeyUsageError> {
-        let Some(raw) = raw else {
-            return Err(SharedKeyUsageError::MissingAeadNonce);
-        };
-        if raw.len() != nonce_size::<GatewayEncryptionAlgorithm>() {
-            return Err(SharedKeyUsageError::MalformedNonce);
-        }
-        Ok(Nonce::<GatewayEncryptionAlgorithm>::clone_from_slice(raw))
-    }
-
-    fn validate_cipher_iv(
-        raw: Option<&[u8]>,
-    ) -> Result<Option<&IV<LegacyGatewayEncryptionAlgorithm>>, SharedKeyUsageError> {
-        let Some(raw) = raw else { return Ok(None) };
-        let iv = if raw.is_empty() {
-            None
-        } else {
-            if raw.len() != iv_size::<LegacyGatewayEncryptionAlgorithm>() {
-                return Err(SharedKeyUsageError::MalformedNonce);
-            }
-            Some(IV::<LegacyGatewayEncryptionAlgorithm>::from_slice(raw))
-        };
-        Ok(iv)
-    }
-
-    pub fn encrypt(
-        &self,
-        plaintext: &[u8],
-        // the best common denominator for converting into 'IV' and 'Nonce' types
-        raw_nonce: Option<&[u8]>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError> {
-        match self {
-            SharedGatewayKey::Current(aes_gcm_siv) => {
-                let nonce = Self::validate_aead_nonce(raw_nonce)?;
-                aes_gcm_siv.encrypt(plaintext, &nonce)
-            }
-            SharedGatewayKey::Legacy(aes_ctr) => {
-                let iv = Self::validate_cipher_iv(raw_nonce)?;
-                Ok(aes_ctr.encrypt_and_tag(plaintext, iv))
-            }
-        }
-    }
-
-    pub fn decrypt(
-        &self,
-        ciphertext: &[u8],
-        // the best common denominator for converting into 'IV' and 'Nonce' types
-        raw_nonce: Option<&[u8]>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError> {
-        match self {
-            SharedGatewayKey::Current(aes_gcm_siv) => {
-                let nonce = Self::validate_aead_nonce(raw_nonce)?;
-                aes_gcm_siv.decrypt(ciphertext, &nonce)
-            }
-            SharedGatewayKey::Legacy(aes_ctr) => {
-                let iv = Self::validate_cipher_iv(raw_nonce)?;
-                aes_ctr.decrypt_tagged(ciphertext, iv)
-            }
-        }
-    }
-
-    // for the legacy keys do not use integrity MAC
-    pub fn encrypt_naive(
-        &self,
-        plaintext: &[u8],
-        // the best common denominator for converting into 'IV' and 'Nonce' types
-        raw_nonce: Option<&[u8]>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError> {
-        match self {
-            SharedGatewayKey::Current(aes_gcm_siv) => {
-                let nonce = Self::validate_aead_nonce(raw_nonce)?;
-                aes_gcm_siv.encrypt(plaintext, &nonce)
-            }
-            SharedGatewayKey::Legacy(aes_ctr) => {
-                let iv = Self::validate_cipher_iv(raw_nonce)?;
-                Ok(aes_ctr.encrypt_without_tagging(plaintext, iv))
-            }
-        }
-    }
-
-    // for the legacy keys do not use integrity MAC
-    pub fn decrypt_naive(
-        &self,
-        ciphertext: &[u8],
-        // the best common denominator for converting into 'IV' and 'Nonce' types
-        raw_nonce: Option<&[u8]>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError> {
-        match self {
-            SharedGatewayKey::Current(aes_gcm_siv) => {
-                let nonce = Self::validate_aead_nonce(raw_nonce)?;
-                aes_gcm_siv.decrypt(ciphertext, &nonce)
-            }
-            SharedGatewayKey::Legacy(aes_ctr) => {
-                let iv = Self::validate_cipher_iv(raw_nonce)?;
-                aes_ctr.decrypt_without_tag(ciphertext, iv)
-            }
-        }
-    }
-}
-
-#[derive(Debug, PartialEq, Serialize, Deserialize, Zeroize, ZeroizeOnDrop)]
-pub struct SharedSymmetricKey(AeadKey<GatewayEncryptionAlgorithm>);
-
-type KeySize = <GatewayEncryptionAlgorithm as KeySizeUser>::KeySize;
-
-#[derive(Debug, Clone, Copy, Error)]
-pub enum SharedKeyConversionError {
-    #[error("the string representation of the shared key was malformed: {0}")]
-    DecodeError(#[from] bs58::decode::Error),
-    #[error(
-        "the received shared keys had invalid size. Got: {received}, but expected: {expected}"
-    )]
-    InvalidSharedKeysSize { received: usize, expected: usize },
-}
-
-impl SharedSymmetricKey {
-    pub fn try_from_bytes(bytes: &[u8]) -> Result<Self, SharedKeyConversionError> {
-        if bytes.len() != KeySize::to_usize() {
-            return Err(SharedKeyConversionError::InvalidSharedKeysSize {
-                received: bytes.len(),
-                expected: KeySize::to_usize(),
-            });
-        }
-
-        Ok(SharedSymmetricKey(GenericArray::clone_from_slice(bytes)))
-    }
-
-    pub fn zeroizing_clone(&self) -> Zeroizing<Self> {
-        Zeroizing::new(SharedSymmetricKey(self.0))
-    }
-
-    pub fn digest(&self) -> Vec<u8> {
-        compute_digest::<blake3::Hasher>(self.as_bytes()).to_vec()
-    }
-
-    pub fn as_bytes(&self) -> &[u8] {
-        self.0.as_slice()
-    }
-
-    pub fn to_bytes(&self) -> Vec<u8> {
-        self.0.iter().copied().collect()
-    }
-
-    pub fn try_from_base58_string<S: Into<String>>(
-        val: S,
-    ) -> Result<Self, SharedKeyConversionError> {
-        let bs58_str = Zeroizing::new(val.into());
-        let decoded = Zeroizing::new(bs58::decode(bs58_str).into_vec()?);
-        Self::try_from_bytes(&decoded)
-    }
-
-    pub fn to_base58_string(&self) -> String {
-        let bytes = Zeroizing::new(self.to_bytes());
-        bs58::encode(bytes).into_string()
-    }
-
-    pub fn encrypt(
-        &self,
-        plaintext: &[u8],
-        nonce: &Nonce<GatewayEncryptionAlgorithm>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError> {
-        aead::encrypt::<GatewayEncryptionAlgorithm>(&self.0, nonce, plaintext).map_err(Into::into)
-    }
-
-    pub fn decrypt(
-        &self,
-        ciphertext: &[u8],
-        nonce: &Nonce<GatewayEncryptionAlgorithm>,
-    ) -> Result<Vec<u8>, SharedKeyUsageError> {
-        aead::decrypt::<GatewayEncryptionAlgorithm>(&self.0, nonce, ciphertext).map_err(Into::into)
-    }
-}
-
-impl PemStorableKey for SharedSymmetricKey {
-    type Error = SharedKeyConversionError;
-
-    fn pem_type() -> &'static str {
-        "AES-256-GCM-SIV GATEWAY SHARED KEY"
-    }
-
-    fn to_bytes(&self) -> Vec<u8> {
-        self.to_bytes()
-    }
-
-    fn from_bytes(bytes: &[u8]) -> Result<Self, Self::Error> {
-        Self::try_from_bytes(bytes)
-    }
-}

common/gateway-requests/src/types/binary_request.rs

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::types::helpers::BinaryData;
-use crate::{GatewayRequestsError, SharedGatewayKey};
+use crate::{GatewayRequestsError, SharedSymmetricKey};
 use nym_sphinx::forwarding::packet::MixPacket;
 use strum::FromRepr;
 use tungstenite::Message;
@@ -57,14 +57,14 @@ impl BinaryRequest {
 
     pub fn try_from_encrypted_tagged_bytes(
         bytes: Vec<u8>,
-        shared_key: &SharedGatewayKey,
+        shared_key: &SharedSymmetricKey,
     ) -> Result<Self, GatewayRequestsError> {
         BinaryData::from_raw(&bytes, shared_key)?.into_request(shared_key)
     }
 
     pub fn into_encrypted_tagged_bytes(
         self,
-        shared_key: &SharedGatewayKey,
+        shared_key: &SharedSymmetricKey,
     ) -> Result<Vec<u8>, GatewayRequestsError> {
         let kind = self.kind();
 
@@ -78,7 +78,7 @@ impl BinaryRequest {
 
     pub fn into_ws_message(
         self,
-        shared_key: &SharedGatewayKey,
+        shared_key: &SharedSymmetricKey,
     ) -> Result<Message, GatewayRequestsError> {
         // all variants are currently encrypted
         let blob = match self {

common/gateway-requests/src/types/binary_response.rs

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::types::helpers::BinaryData;
-use crate::{GatewayRequestsError, SharedGatewayKey};
+use crate::{GatewayRequestsError, SharedSymmetricKey};
 use strum::FromRepr;
 use tungstenite::Message;
 
@@ -38,14 +38,14 @@ impl BinaryResponse {
 
     pub fn try_from_encrypted_tagged_bytes(
         bytes: Vec<u8>,
-        shared_key: &SharedGatewayKey,
+        shared_key: &SharedSymmetricKey,
     ) -> Result<Self, GatewayRequestsError> {
         BinaryData::from_raw(&bytes, shared_key)?.into_response(shared_key)
     }
 
     pub fn into_encrypted_tagged_bytes(
         self,
-        shared_key: &SharedGatewayKey,
+        shared_key: &SharedSymmetricKey,
     ) -> Result<Vec<u8>, GatewayRequestsError> {
         let kind = self.kind();
 
@@ -58,7 +58,7 @@ impl BinaryResponse {
 
     pub fn into_ws_message(
         self,
-        shared_key: &SharedGatewayKey,
+        shared_key: &SharedSymmetricKey,
     ) -> Result<Message, GatewayRequestsError> {
         // all variants are currently encrypted
         let blob = match self {

common/gateway-requests/src/types/helpers.rs

@@ -3,12 +3,12 @@
 
 use crate::{
     BinaryRequest, BinaryRequestKind, BinaryResponse, BinaryResponseKind, GatewayRequestsError,
-    SharedGatewayKey,
+    SharedSymmetricKey,
 };
 use std::iter::once;
 
 // each binary message consists of the following structure (for non-legacy messages)
-// KIND || ENC_FLAG || MAYBE_NONCE || CIPHERTEXT/PLAINTEXT
+// KIND || ENC_FLAG || NONCE || CIPHERTEXT/PLAINTEXT
 // first byte is the kind of data to influence further serialisation/deseralisation
 // second byte is a flag indicating whether the content is encrypted
 // then it's followed by a pseudorandom nonce, assuming encryption is used
@@ -16,43 +16,25 @@ use std::iter::once;
 pub struct BinaryData<'a> {
     kind: u8,
     encrypted: bool,
-    maybe_nonce: Option<&'a [u8]>,
+    nonce: &'a [u8],
     data: &'a [u8],
 }
 
 impl<'a> BinaryData<'a> {
     // serialises possibly encrypted data into bytes to be put on the wire
-    pub fn into_raw(self, legacy: bool) -> Vec<u8> {
-        if legacy {
-            return self.data.to_vec();
-        }
-
-        let i = once(self.kind).chain(once(if self.encrypted { 1 } else { 0 }));
-        if let Some(nonce) = self.maybe_nonce {
-            i.chain(nonce.iter().copied())
-                .chain(self.data.iter().copied())
-                .collect()
-        } else {
-            i.chain(self.data.iter().copied()).collect()
-        }
+    pub fn into_raw(self) -> Vec<u8> {
+        once(self.kind)
+            .chain(once(if self.encrypted { 1 } else { 0 }))
+            .chain(self.nonce.iter().copied())
+            .chain(self.data.iter().copied())
+            .collect()
     }
 
     // attempts to perform basic parsing on bytes received from the wire
     pub fn from_raw(
         raw: &'a [u8],
-        available_key: &SharedGatewayKey,
+        available_key: &SharedSymmetricKey,
     ) -> Result<Self, GatewayRequestsError> {
-        // if we're using legacy key, it's quite simple:
-        // it's always encrypted with no nonce and the request/response kind is always 1
-        if available_key.is_legacy() {
-            return Ok(BinaryData {
-                kind: 1,
-                encrypted: true,
-                maybe_nonce: None,
-                data: raw,
-            });
-        }
-
         if raw.len() < 2 {
             return Err(GatewayRequestsError::TooShortRequest);
         }
@@ -74,7 +56,7 @@ impl<'a> BinaryData<'a> {
         Ok(BinaryData {
             kind,
             encrypted,
-            maybe_nonce: Some(&raw[2..2 + available_key.nonce_size()]),
+            nonce: &raw[2..2 + available_key.nonce_size()],
             data: &raw[2 + available_key.nonce_size()..],
         })
     }
@@ -83,30 +65,32 @@ impl<'a> BinaryData<'a> {
     pub fn make_encrypted_blob(
         kind: u8,
         plaintext: &[u8],
-        key: &SharedGatewayKey,
+        key: &SharedSymmetricKey,
     ) -> Result<Vec<u8>, GatewayRequestsError> {
-        let maybe_nonce = key.random_nonce_or_zero_iv();
+        let nonce = key.random_nonce();
 
-        let ciphertext = key.encrypt(plaintext, maybe_nonce.as_deref())?;
+        let ciphertext = key.encrypt(plaintext, &nonce)?;
         Ok(BinaryData {
             kind,
             encrypted: true,
-            maybe_nonce: maybe_nonce.as_deref(),
+            nonce: &nonce,
             data: &ciphertext,
         }
-        .into_raw(key.is_legacy()))
+        .into_raw())
     }
 
     // attempts to parse previously recovered bytes into a [`BinaryRequest`]
     pub fn into_request(
         self,
-        key: &SharedGatewayKey,
+        key: &SharedSymmetricKey,
     ) -> Result<BinaryRequest, GatewayRequestsError> {
         let kind = BinaryRequestKind::from_repr(self.kind)
             .ok_or(GatewayRequestsError::UnknownRequestKind { kind: self.kind })?;
 
         let plaintext = if self.encrypted {
-            &*key.decrypt(self.data, self.maybe_nonce)?
+            let nonce = SharedSymmetricKey::validate_aead_nonce(self.nonce)?;
+
+            &*key.decrypt(self.data, &nonce)?
         } else {
             self.data
         };
@@ -117,13 +101,15 @@ impl<'a> BinaryData<'a> {
     // attempts to parse previously recovered bytes into a [`BinaryResponse`]
     pub fn into_response(
         self,
-        key: &SharedGatewayKey,
+        key: &SharedSymmetricKey,
     ) -> Result<BinaryResponse, GatewayRequestsError> {
         let kind = BinaryResponseKind::from_repr(self.kind)
             .ok_or(GatewayRequestsError::UnknownResponseKind { kind: self.kind })?;
 
         let plaintext = if self.encrypted {
-            &*key.decrypt(self.data, self.maybe_nonce)?
+            let nonce = SharedSymmetricKey::validate_aead_nonce(self.nonce)?;
+
+            &*key.decrypt(self.data, &nonce)?
         } else {
             self.data
         };

common/gateway-requests/src/types/registration_handshake_wrapper.rs

@@ -10,7 +10,7 @@ use std::str::FromStr;
 pub enum RegistrationHandshake {
     HandshakePayload {
         #[serde(default)]
-        protocol_version: Option<GatewayProtocolVersion>,
+        protocol_version: GatewayProtocolVersion,
         data: Vec<u8>,
     },
     HandshakeError {
@@ -19,7 +19,7 @@ pub enum RegistrationHandshake {
 }
 
 impl RegistrationHandshake {
-    pub fn new_payload(data: Vec<u8>, protocol_version: Option<GatewayProtocolVersion>) -> Self {
+    pub fn new_payload(data: Vec<u8>, protocol_version: GatewayProtocolVersion) -> Self {
         RegistrationHandshake::HandshakePayload {
             protocol_version,
             data,
@@ -66,7 +66,7 @@ mod tests {
     fn handshake_payload_can_be_deserialized_into_register_handshake_init_request() {
         let handshake_data = vec![1, 2, 3, 4, 5, 6];
         let handshake_payload_with_protocol = RegistrationHandshake::HandshakePayload {
-            protocol_version: Some(42),
+            protocol_version: 42,
             data: handshake_data.clone(),
         };
         let serialized = serde_json::to_string(&handshake_payload_with_protocol).unwrap();
@@ -77,25 +77,7 @@ mod tests {
                 protocol_version,
                 data,
             } => {
-                assert_eq!(protocol_version, Some(42));
-                assert_eq!(data, handshake_data)
-            }
-            _ => panic!("this branch shouldn't have been reached!"),
-        }
-
-        let handshake_payload_without_protocol = RegistrationHandshake::HandshakePayload {
-            protocol_version: None,
-            data: handshake_data.clone(),
-        };
-        let serialized = serde_json::to_string(&handshake_payload_without_protocol).unwrap();
-        let deserialized = ClientControlRequest::try_from(serialized).unwrap();
-
-        match deserialized {
-            ClientControlRequest::RegisterHandshakeInitRequest {
-                protocol_version,
-                data,
-            } => {
-                assert!(protocol_version.is_none());
+                assert_eq!(protocol_version, 42);
                 assert_eq!(data, handshake_data)
             }
             _ => panic!("this branch shouldn't have been reached!"),

common/gateway-requests/src/types/text_request/authenticate.rs

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 
 use crate::{
-    AuthenticationFailure, GatewayProtocolVersion, GatewayRequestsError, SharedGatewayKey,
+    AuthenticationFailure, GatewayProtocolVersion, GatewayRequestsError, SharedSymmetricKey,
 };
 use nym_crypto::asymmetric::ed25519;
 use serde::{Deserialize, Serialize};
@@ -23,7 +23,7 @@ pub struct AuthenticateRequest {
 impl AuthenticateRequest {
     pub fn new(
         protocol_version: GatewayProtocolVersion,
-        shared_key: &SharedGatewayKey,
+        shared_key: &SharedSymmetricKey,
         identity_keys: &ed25519::KeyPair,
     ) -> Result<AuthenticateRequest, GatewayRequestsError> {
         let content = AuthenticateRequestContent::new(
@@ -72,14 +72,14 @@ impl AuthenticateRequest {
 
     pub fn verify_ciphertext(
         &self,
-        shared_key: &SharedGatewayKey,
+        shared_key: &SharedSymmetricKey,
     ) -> Result<(), AuthenticationFailure> {
         let expected = shared_key.encrypt(
             self.content
                 .client_identity
                 .derive_destination_address()
                 .as_bytes_ref(),
-            Some(&self.content.nonce),
+            &SharedSymmetricKey::validate_aead_nonce(&self.content.nonce)?,
         )?;
 
         if !bool::from(expected.ct_eq(&self.content.address_ciphertext)) {
@@ -117,20 +117,19 @@ pub struct AuthenticateRequestContent {
 impl AuthenticateRequestContent {
     fn new(
         protocol_version: u8,
-        shared_key: &SharedGatewayKey,
+        shared_key: &SharedSymmetricKey,
         client_identity: ed25519::PublicKey,
     ) -> Result<AuthenticateRequestContent, GatewayRequestsError> {
-        let nonce = shared_key.random_nonce_or_iv();
+        let nonce = shared_key.random_nonce();
         let destination_address = client_identity.derive_destination_address();
 
-        let address_ciphertext =
-            shared_key.encrypt(destination_address.as_bytes_ref(), Some(&nonce))?;
+        let address_ciphertext = shared_key.encrypt(destination_address.as_bytes_ref(), &nonce)?;
         let now = OffsetDateTime::now_utc();
         Ok(AuthenticateRequestContent {
             protocol_version,
             client_identity,
             address_ciphertext,
-            nonce,
+            nonce: nonce.to_vec(),
             request_unix_timestamp: now.unix_timestamp() as u64, // SAFETY: we're running this in post 1970...
         })
     }

common/gateway-requests/src/types/text_request/mod.rs

@@ -3,13 +3,9 @@
 
 use crate::models::CredentialSpendingRequest;
 use crate::text_request::authenticate::AuthenticateRequest;
-use crate::{
-    GatewayProtocolVersion, GatewayRequestsError, SharedGatewayKey, SymmetricKey,
-    AES_GCM_SIV_PROTOCOL_VERSION, CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION, INITIAL_PROTOCOL_VERSION,
-};
+use crate::{GatewayProtocolVersion, GatewayRequestsError, SharedSymmetricKey};
 use nym_credentials_interface::CredentialSpendingData;
 use nym_crypto::asymmetric::ed25519;
-use nym_sphinx::DestinationAddressBytes;
 use nym_statistics_common::types::SessionType;
 use serde::{Deserialize, Serialize};
 use std::str::FromStr;
@@ -21,23 +17,14 @@ pub mod authenticate;
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[non_exhaustive]
 pub enum ClientRequest {
-    UpgradeKey {
-        hkdf_salt: Vec<u8>,
-        derived_key_digest: Vec<u8>,
-    },
-    ForgetMe {
-        client: bool,
-        stats: bool,
-    },
-    RememberMe {
-        session_type: SessionType,
-    },
+    ForgetMe { client: bool, stats: bool },
+    RememberMe { session_type: SessionType },
 }
 
 impl ClientRequest {
-    pub fn encrypt<S: SymmetricKey>(
+    pub fn encrypt(
         &self,
-        key: &S,
+        key: &SharedSymmetricKey,
     ) -> Result<ClientControlRequest, GatewayRequestsError> {
         // we're using json representation for few reasons:
         // - ease of re-implementation in other languages (compared to for example bincode)
@@ -47,17 +34,21 @@ impl ClientRequest {
         // SAFETY: the trait has been derived correctly with no weird variants
         #[allow(clippy::unwrap_used)]
         let plaintext = serde_json::to_vec(self).unwrap();
-        let nonce = key.random_nonce_or_iv();
-        let ciphertext = key.encrypt(&plaintext, Some(&nonce))?;
-        Ok(ClientControlRequest::EncryptedRequest { ciphertext, nonce })
+        let nonce = key.random_nonce();
+        let ciphertext = key.encrypt(&plaintext, &nonce)?;
+        Ok(ClientControlRequest::EncryptedRequest {
+            ciphertext,
+            nonce: nonce.to_vec(),
+        })
     }
 
-    pub fn decrypt<S: SymmetricKey>(
+    pub fn decrypt(
         ciphertext: &[u8],
         nonce: &[u8],
-        key: &S,
+        key: &SharedSymmetricKey,
     ) -> Result<Self, GatewayRequestsError> {
-        let plaintext = key.decrypt(ciphertext, Some(nonce))?;
+        let nonce = SharedSymmetricKey::validate_aead_nonce(nonce)?;
+        let plaintext = key.decrypt(ciphertext, &nonce)?;
         serde_json::from_slice(&plaintext)
             .map_err(|source| GatewayRequestsError::MalformedRequest { source })
     }
@@ -68,35 +59,20 @@ impl ClientRequest {
 #[serde(tag = "type", rename_all = "camelCase")]
 #[non_exhaustive]
 pub enum ClientControlRequest {
-    // TODO: should this also contain a MAC considering that at this point we already
-    // have the shared key derived?
-    Authenticate {
-        #[serde(default)]
-        protocol_version: Option<GatewayProtocolVersion>,
-        address: String,
-        enc_address: String,
-        iv: String,
-    },
-
     AuthenticateV2(Box<AuthenticateRequest>),
 
     #[serde(alias = "handshakePayload")]
     RegisterHandshakeInitRequest {
         #[serde(default)]
-        protocol_version: Option<GatewayProtocolVersion>,
+        protocol_version: GatewayProtocolVersion,
         data: Vec<u8>,
     },
-    BandwidthCredential {
-        enc_credential: Vec<u8>,
-        iv: Vec<u8>,
-    },
-    BandwidthCredentialV2 {
-        enc_credential: Vec<u8>,
-        iv: Vec<u8>,
-    },
     EcashCredential {
         enc_credential: Vec<u8>,
-        iv: Vec<u8>,
+        // Old gateways only understand `iv` so rename the field, but have nonce as an alias for next version update, to then phase out `iv`
+        #[serde(rename = "iv")]
+        #[serde(alias = "nonce")]
+        nonce: Vec<u8>,
     },
     UpgradeModeJWT {
         // no need to encrypt it as it's public anyway
@@ -109,40 +85,29 @@ pub enum ClientControlRequest {
     },
     SupportedProtocol {},
     // if you're adding new variants here, consider putting them inside `ClientRequest` instead
+
+    // NO LONGER SUPPORTED
+    Authenticate {
+        #[serde(default)]
+        protocol_version: Option<GatewayProtocolVersion>,
+        address: String,
+        enc_address: String,
+        iv: String,
+    },
+
+    BandwidthCredential {
+        enc_credential: Vec<u8>,
+        iv: Vec<u8>,
+    },
+    BandwidthCredentialV2 {
+        enc_credential: Vec<u8>,
+        iv: Vec<u8>,
+    },
 }
 
 impl ClientControlRequest {
-    pub fn new_legacy_authenticate(
-        address: DestinationAddressBytes,
-        shared_key: &SharedGatewayKey,
-        uses_credentials: bool,
-    ) -> Result<Self, GatewayRequestsError> {
-        // if we're encrypting with non-legacy key, the remote must support AES256-GCM-SIV
-        // since we are using legacy authentication, the gateway definitely doesn't understand the protocol downgrade,
-        // so use the lowest possible version we can
-        let protocol_version = if !shared_key.is_legacy() {
-            Some(AES_GCM_SIV_PROTOCOL_VERSION)
-        } else if uses_credentials {
-            Some(CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION)
-        } else {
-            // if we're not going to be using credentials, advertise lower protocol version to allow connection
-            // to wider range of gateways
-            Some(INITIAL_PROTOCOL_VERSION)
-        };
-
-        let nonce = shared_key.random_nonce_or_iv();
-        let ciphertext = shared_key.encrypt_naive(address.as_bytes_ref(), Some(&nonce))?;
-
-        Ok(ClientControlRequest::Authenticate {
-            protocol_version,
-            address: address.as_base58_string(),
-            enc_address: bs58::encode(&ciphertext).into_string(),
-            iv: bs58::encode(&nonce).into_string(),
-        })
-    }
-
     pub fn new_authenticate_v2(
-        shared_key: &SharedGatewayKey,
+        shared_key: &SharedSymmetricKey,
         identity_keys: &ed25519::KeyPair,
         protocol_version: GatewayProtocolVersion,
     ) -> Result<Self, GatewayRequestsError> {
@@ -174,26 +139,27 @@ impl ClientControlRequest {
 
     pub fn new_enc_ecash_credential(
         credential: CredentialSpendingData,
-        shared_key: &SharedGatewayKey,
+        shared_key: &SharedSymmetricKey,
     ) -> Result<Self, GatewayRequestsError> {
         let cred = CredentialSpendingRequest::new(credential);
         let serialized_credential = cred.to_bytes();
 
-        let nonce = shared_key.random_nonce_or_iv();
-        let enc_credential = shared_key.encrypt(&serialized_credential, Some(&nonce))?;
+        let nonce = shared_key.random_nonce();
+        let enc_credential = shared_key.encrypt(&serialized_credential, &nonce)?;
 
         Ok(ClientControlRequest::EcashCredential {
             enc_credential,
-            iv: nonce,
+            nonce: nonce.to_vec(),
         })
     }
 
     pub fn try_from_enc_ecash_credential(
         enc_credential: Vec<u8>,
-        shared_key: &SharedGatewayKey,
-        iv: Vec<u8>,
+        shared_key: &SharedSymmetricKey,
+        nonce: Vec<u8>,
     ) -> Result<CredentialSpendingRequest, GatewayRequestsError> {
-        let credential_bytes = shared_key.decrypt(&enc_credential, Some(&iv))?;
+        let nonce = SharedSymmetricKey::validate_aead_nonce(&nonce)?;
+        let credential_bytes = shared_key.decrypt(&enc_credential, &nonce)?;
         CredentialSpendingRequest::try_from_bytes(credential_bytes.as_slice())
             .map_err(|_| GatewayRequestsError::MalformedEncryption)
     }

common/gateway-requests/src/types/text_response.rs

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::{
-    GatewayProtocolVersion, GatewayRequestsError, SimpleGatewayRequestsError, SymmetricKey,
+    GatewayProtocolVersion, GatewayRequestsError, SharedSymmetricKey, SimpleGatewayRequestsError,
 };
 use serde::{Deserialize, Serialize};
 use tungstenite::Message;
@@ -12,15 +12,14 @@ use tungstenite::Message;
 #[derive(Serialize, Deserialize, Debug)]
 #[non_exhaustive]
 pub enum SensitiveServerResponse {
-    KeyUpgradeAck {},
     ForgetMeAck {},
     RememberMeAck {},
 }
 
 impl SensitiveServerResponse {
-    pub fn encrypt<S: SymmetricKey>(
+    pub fn encrypt(
         &self,
-        key: &S,
+        key: &SharedSymmetricKey,
     ) -> Result<ServerResponse, GatewayRequestsError> {
         // we're using json representation for few reasons:
         // - ease of re-implementation in other languages (compared to for example bincode)
@@ -30,17 +29,21 @@ impl SensitiveServerResponse {
         // SAFETY: the trait has been derived correctly with no weird variants
         #[allow(clippy::unwrap_used)]
         let plaintext = serde_json::to_vec(self).unwrap();
-        let nonce = key.random_nonce_or_iv();
-        let ciphertext = key.encrypt(&plaintext, Some(&nonce))?;
-        Ok(ServerResponse::EncryptedResponse { ciphertext, nonce })
+        let nonce = key.random_nonce();
+        let ciphertext = key.encrypt(&plaintext, &nonce)?;
+        Ok(ServerResponse::EncryptedResponse {
+            ciphertext,
+            nonce: nonce.to_vec(),
+        })
     }
 
-    pub fn decrypt<S: SymmetricKey>(
+    pub fn decrypt(
         ciphertext: &[u8],
         nonce: &[u8],
-        key: &S,
+        key: &SharedSymmetricKey,
     ) -> Result<Self, GatewayRequestsError> {
-        let plaintext = key.decrypt(ciphertext, Some(nonce))?;
+        let nonce = SharedSymmetricKey::validate_aead_nonce(nonce)?;
+        let plaintext = key.decrypt(ciphertext, &nonce)?;
         serde_json::from_slice(&plaintext)
             .map_err(|source| GatewayRequestsError::MalformedRequest { source })
     }
@@ -72,7 +75,7 @@ pub struct SendResponse {
 pub enum ServerResponse {
     Authenticate {
         #[serde(default)]
-        protocol_version: Option<GatewayProtocolVersion>,
+        protocol_version: GatewayProtocolVersion,
         status: bool,
         bandwidth_remaining: i64,
 
@@ -83,7 +86,7 @@ pub enum ServerResponse {
     },
     Register {
         #[serde(default)]
-        protocol_version: Option<GatewayProtocolVersion>,
+        protocol_version: GatewayProtocolVersion,
         status: bool,
 
         /// Flag indicating whether the gateway has detected the system is undergoing the upgrade

common/gateway-storage/migrations/20251126120000_remove_aes128ctr_key.sql

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+ * SPDX-License-Identifier: GPL-3.0-only
+ */
+
+
+-- make aes256gcm column non-nullable and drop any clients that still use the legacy keys
+CREATE TABLE shared_keys_tmp
+(
+    client_id                  INTEGER NOT NULL PRIMARY KEY REFERENCES clients (id),
+    client_address_bs58        TEXT    NOT NULL UNIQUE,
+    derived_aes256_gcm_siv_key BLOB    NOT NULL,
+    last_used_authentication TIMESTAMP WITHOUT TIME ZONE
+);
+
+INSERT INTO shared_keys_tmp (client_id, client_address_bs58, derived_aes256_gcm_siv_key, last_used_authentication)
+SELECT client_id, client_address_bs58, derived_aes256_gcm_siv_key, last_used_authentication
+FROM shared_keys
+WHERE derived_aes256_gcm_siv_key IS NOT NULL;
+
+DROP TABLE shared_keys;
+ALTER TABLE shared_keys_tmp
+    RENAME TO shared_keys;

common/gateway-storage/src/lib.rs

@@ -9,7 +9,7 @@ use models::{
     VerifiedTicket, WireguardPeer,
 };
 use nym_credentials_interface::ClientTicket;
-use nym_gateway_requests::shared_key::SharedGatewayKey;
+use nym_gateway_requests::shared_key::SharedSymmetricKey;
 use nym_sphinx::DestinationAddressBytes;
 use shared_keys::SharedKeysManager;
 use sqlx::{
@@ -165,7 +165,7 @@ impl SharedKeyGatewayStorage for GatewayStorage {
     async fn insert_shared_keys(
         &self,
         client_address: DestinationAddressBytes,
-        shared_keys: &SharedGatewayKey,
+        shared_keys: &SharedSymmetricKey,
     ) -> Result<i64, GatewayStorageError> {
         let client_address_bs58 = client_address.as_base58_string();
         let client_id = match self
@@ -184,8 +184,7 @@ impl SharedKeyGatewayStorage for GatewayStorage {
             .insert_shared_keys(
                 client_id,
                 client_address_bs58,
-                shared_keys.aes128_ctr_hmac_bs58().as_deref(),
-                shared_keys.aes256_gcm_siv().as_deref(),
+                shared_keys.to_bytes().as_ref(),
             )
             .await?;
         Ok(client_id)

common/gateway-storage/src/models.rs

@@ -3,7 +3,7 @@
 
 use crate::{error::GatewayStorageError, make_bincode_serializer};
 use nym_credentials_interface::{AvailableBandwidth, ClientTicket, CredentialSpendingData};
-use nym_gateway_requests::shared_key::{LegacySharedKeys, SharedGatewayKey, SharedSymmetricKey};
+use nym_gateway_requests::shared_key::SharedSymmetricKey;
 use sqlx::FromRow;
 use time::OffsetDateTime;
 
@@ -18,33 +18,16 @@ pub struct PersistedSharedKeys {
 
     #[allow(dead_code)]
     pub client_address_bs58: String,
-    pub derived_aes128_ctr_blake3_hmac_keys_bs58: Option<String>,
-    pub derived_aes256_gcm_siv_key: Option<Vec<u8>>,
+    pub derived_aes256_gcm_siv_key: Vec<u8>,
     pub last_used_authentication: Option<OffsetDateTime>,
 }
 
-impl TryFrom<PersistedSharedKeys> for SharedGatewayKey {
+impl TryFrom<PersistedSharedKeys> for SharedSymmetricKey {
     type Error = GatewayStorageError;
 
     fn try_from(value: PersistedSharedKeys) -> Result<Self, Self::Error> {
-        match (
-            &value.derived_aes256_gcm_siv_key,
-            &value.derived_aes128_ctr_blake3_hmac_keys_bs58,
-        ) {
-            (None, None) => Err(GatewayStorageError::MissingSharedKey {
-                id: value.client_id,
-            }),
-            (Some(aes256gcm_siv), _) => {
-                let current_key = SharedSymmetricKey::try_from_bytes(aes256gcm_siv)
-                    .map_err(|source| GatewayStorageError::DataCorruption(source.to_string()))?;
-                Ok(SharedGatewayKey::Current(current_key))
-            }
-            (None, Some(aes128ctr_hmac)) => {
-                let legacy_key = LegacySharedKeys::try_from_base58_string(aes128ctr_hmac)
-                    .map_err(|source| GatewayStorageError::DataCorruption(source.to_string()))?;
-                Ok(SharedGatewayKey::Legacy(legacy_key))
-            }
-        }
+        SharedSymmetricKey::try_from_bytes(&value.derived_aes256_gcm_siv_key)
+            .map_err(|source| GatewayStorageError::DataCorruption(source.to_string()))
     }
 }
 

common/gateway-storage/src/shared_keys.rs

@@ -42,26 +42,22 @@ impl SharedKeysManager {
         &self,
         client_id: i64,
         client_address_bs58: String,
-        derived_aes128_ctr_blake3_hmac_keys_bs58: Option<&String>,
-        derived_aes256_gcm_siv_key: Option<&Vec<u8>>,
+        derived_aes256_gcm_siv_key: &Vec<u8>,
     ) -> Result<(), sqlx::Error> {
         // https://stackoverflow.com/a/20310838
         // we don't want to be using `INSERT OR REPLACE INTO` due to the foreign key on `available_bandwidth` if the entry already exists
         sqlx::query!(
             r#"
-                INSERT OR IGNORE INTO shared_keys(client_id, client_address_bs58, derived_aes128_ctr_blake3_hmac_keys_bs58, derived_aes256_gcm_siv_key) VALUES (?, ?, ?, ?);
+                INSERT OR IGNORE INTO shared_keys(client_id, client_address_bs58,derived_aes256_gcm_siv_key) VALUES (?, ?, ?);
 
                 UPDATE shared_keys
                 SET
-                    derived_aes128_ctr_blake3_hmac_keys_bs58 = ?,
                     derived_aes256_gcm_siv_key = ?
                 WHERE client_address_bs58 = ?
             "#,
             client_id,
             client_address_bs58,
-            derived_aes128_ctr_blake3_hmac_keys_bs58,
             derived_aes256_gcm_siv_key,
-            derived_aes128_ctr_blake3_hmac_keys_bs58,
             derived_aes256_gcm_siv_key,
             client_address_bs58,
         ).execute(&self.connection_pool).await?;

common/gateway-storage/src/traits.rs

@@ -3,7 +3,7 @@
 
 use async_trait::async_trait;
 use nym_credentials_interface::ClientTicket;
-use nym_gateway_requests::SharedGatewayKey;
+use nym_gateway_requests::SharedSymmetricKey;
 use nym_sphinx::DestinationAddressBytes;
 use time::OffsetDateTime;
 
@@ -25,7 +25,7 @@ pub trait SharedKeyGatewayStorage {
     async fn insert_shared_keys(
         &self,
         client_address: DestinationAddressBytes,
-        shared_keys: &SharedGatewayKey,
+        shared_keys: &SharedSymmetricKey,
     ) -> Result<i64, GatewayStorageError>;
     async fn get_shared_keys(
         &self,

common/http-api-client-macro/src/lib.rs

@@ -23,7 +23,7 @@
 //!     priority = 10;  // Optional, defaults to 0
 //!     timeout = std::time::Duration::from_secs(30),
 //!     gzip = true,
-//!     user_agent = "MyApp/1.0"
+//!     user_agent = "Nym/1.0"
 //! );
 //! ```
 //!
@@ -60,9 +60,8 @@
 //! - Positive priorities: Late configuration (e.g., 100 for overrides)
 
 use proc_macro::TokenStream;
-use proc_macro_crate::{FoundCrate, crate_name};
-use proc_macro2::{Span, TokenStream as TokenStream2};
-use quote::{format_ident, quote};
+use proc_macro2::TokenStream as TokenStream2;
+use quote::quote;
 use syn::{
     Expr, Ident, LitInt, Result, Token, braced,
     parse::{Parse, ParseStream},
@@ -74,22 +73,22 @@ use syn::{
 // ------------------ core crate path resolution ------------------
 
 fn core_path() -> TokenStream2 {
+    use proc_macro_crate::{FoundCrate, crate_name};
+
     match crate_name("nym-http-api-client") {
         Ok(FoundCrate::Itself) => quote!(crate),
         Ok(FoundCrate::Name(name)) => {
-            let ident = Ident::new(&name, Span::call_site());
+            let ident = Ident::new(&name, proc_macro2::Span::call_site());
             quote!( ::#ident )
         }
-        Err(_) => {
-            // Fallback if the crate is not found by name (unlikely if deps set up correctly)
-            quote!(::nym_http_api_client)
-        }
+        Err(_) => quote!(::nym_http_api_client),
     }
 }
 
 // ------------------ DSL parsing ------------------
 
 struct Items(Punctuated<Item, Token![,]>);
+
 impl Parse for Items {
     fn parse(input: ParseStream<'_>) -> Result<Self> {
         Ok(Self(Punctuated::parse_terminated(input)?))
@@ -101,19 +100,19 @@ enum Item {
         key: Ident,
         _eq: Token![=],
         value: Expr,
-    }, // foo = EXPR
+    },
     Call {
         key: Ident,
         args: Punctuated<Expr, Token![,]>,
         _p: token::Paren,
-    }, // foo(a,b)
+    },
     DefaultHeaders {
         _key: Ident,
         map: HeaderMapInit,
-    }, // default_headers { ... }
+    },
     Flag {
         key: Ident,
-    }, // foo
+    },
 }
 
 impl Parse for Item {
@@ -125,16 +124,19 @@ impl Parse for Item {
             let value: Expr = input.parse()?;
             return Ok(Self::Assign { key, _eq, value });
         }
+
         if input.peek(token::Paren) {
             let content;
             let _p = syn::parenthesized!(content in input);
             let args = Punctuated::<Expr, Token![,]>::parse_terminated(&content)?;
             return Ok(Self::Call { key, args, _p });
         }
-        if input.peek(token::Brace) && key == format_ident!("default_headers") {
+
+        if input.peek(token::Brace) && key == quote::format_ident!("default_headers") {
             let map = input.parse::<HeaderMapInit>()?;
             return Ok(Self::DefaultHeaders { _key: key, map });
         }
+
         Ok(Self::Flag { key })
     }
 }
@@ -144,6 +146,7 @@ struct HeaderPair {
     _arrow: Token![=>],
     v: Expr,
 }
+
 impl Parse for HeaderPair {
     fn parse(input: ParseStream<'_>) -> Result<Self> {
         Ok(Self {
@@ -158,6 +161,7 @@ struct HeaderMapInit {
     _brace: token::Brace,
     pairs: Punctuated<HeaderPair, Token![,]>,
 }
+
 impl Parse for HeaderMapInit {
     fn parse(input: ParseStream<'_>) -> Result<Self> {
         let content;
@@ -170,6 +174,7 @@ impl Parse for HeaderMapInit {
 // Generate statements that mutate a builder named `b` using the resolved core path.
 fn to_stmts(items: Items, core: &TokenStream2) -> TokenStream2 {
     let mut stmts = Vec::new();
+
     for it in items.0 {
         match it {
             Item::Assign { key, value, .. } => {
@@ -204,9 +209,73 @@ fn to_stmts(items: Items, core: &TokenStream2) -> TokenStream2 {
             }
         }
     }
+
     quote! { #(#stmts)* }
 }
 
+struct MaybePrioritized {
+    priority: i32,
+    items: Items,
+}
+
+impl Parse for MaybePrioritized {
+    fn parse(input: ParseStream<'_>) -> Result<Self> {
+        // Optional header: `priority = <int> ;`
+        let fork = input.fork();
+        let mut priority = 0i32;
+
+        if fork.peek(Ident) && fork.parse::<Ident>()? == "priority" && fork.peek(Token![=]) {
+            // commit
+            let _ = input.parse::<Ident>()?; // priority
+            let _ = input.parse::<Token![=]>()?; // =
+            let lit: LitInt = input.parse()?;
+            priority = lit.base10_parse()?;
+            let _ = input.parse::<Token![;]>()?; // ;
+        }
+
+        let items = input.parse::<Items>()?;
+        Ok(Self { priority, items })
+    }
+}
+
+fn describe_items(items: &Items) -> String {
+    use std::fmt::Write;
+
+    let mut buf = String::new();
+
+    for (idx, item) in items.0.iter().enumerate() {
+        if idx > 0 {
+            buf.push_str(", ");
+        }
+
+        match item {
+            Item::Assign { key, value, .. } => {
+                let k = quote!(#key).to_string();
+                let v = quote!(#value).to_string();
+                let _ = write!(buf, "{}={}", k, v);
+            }
+            Item::Call { key, args, .. } => {
+                let k = quote!(#key).to_string();
+                let args_str = args
+                    .iter()
+                    .map(|a| quote!(#a).to_string())
+                    .collect::<Vec<_>>()
+                    .join(", ");
+                let _ = write!(buf, "{}({})", k, args_str);
+            }
+            Item::Flag { key } => {
+                let k = quote!(#key).to_string();
+                let _ = write!(buf, "{}()", k);
+            }
+            Item::DefaultHeaders { .. } => {
+                buf.push_str("default_headers{...}");
+            }
+        }
+    }
+
+    buf
+}
+
 // ------------------ client_cfg! ------------------
 
 /// Creates a closure that configures a `ReqwestClientBuilder`.
@@ -236,30 +305,6 @@ pub fn client_cfg(input: TokenStream) -> TokenStream {
     out.into()
 }
 
-// ------------------ client_defaults! with optional priority header ------------------
-
-struct MaybePrioritized {
-    priority: i32,
-    items: Items,
-}
-impl Parse for MaybePrioritized {
-    fn parse(input: ParseStream<'_>) -> Result<Self> {
-        // Optional header: `priority = <int> ;`
-        let fork = input.fork();
-        let mut priority = 0i32;
-        if fork.peek(Ident) && fork.parse::<Ident>()? == "priority" && fork.peek(Token![=]) {
-            // commit
-            let _ = input.parse::<Ident>()?; // priority
-            let _ = input.parse::<Token![=]>()?;
-            let lit: LitInt = input.parse()?;
-            priority = lit.base10_parse()?;
-            let _ = input.parse::<Token![;]>()?;
-        }
-        let items = input.parse::<Items>()?;
-        Ok(Self { priority, items })
-    }
-}
-
 /// Registers global default configurations for HTTP clients.
 ///
 /// This macro submits a configuration record to the global registry that will
@@ -280,7 +325,7 @@ impl Parse for MaybePrioritized {
 ///     connect_timeout = std::time::Duration::from_secs(10),
 ///     pool_max_idle_per_host = 32,
 ///     default_headers {
-///         "User-Agent" => "MyApp/1.0",
+///         "User-Agent" => "Nym/1.0",
 ///         "Accept" => "application/json"
 ///     }
 /// );
@@ -290,99 +335,50 @@ pub fn client_defaults(input: TokenStream) -> TokenStream {
     let MaybePrioritized { priority, items } = parse_macro_input!(input as MaybePrioritized);
     let core = core_path();
 
-    // Generate a description of what this config does (before consuming items)
-    let config_description = if cfg!(feature = "debug-inventory") {
-        let descriptions = items
-            .0
-            .iter()
-            .map(|item| match item {
-                Item::Assign { key, value, .. } => {
-                    format!("{}={:?}", quote!(#key), quote!(#value).to_string())
-                }
-                Item::Call { key, args, .. } => {
-                    let args_str = args
-                        .iter()
-                        .map(|a| quote!(#a).to_string())
-                        .collect::<Vec<_>>()
-                        .join(", ");
-                    format!("{}({})", quote!(#key), args_str)
-                }
-                Item::Flag { key } => {
-                    format!("{}()", quote!(#key))
-                }
-                Item::DefaultHeaders { .. } => "default_headers{{...}}".to_string(),
-            })
-            .collect::<Vec<_>>()
-            .join(", ");
+    // Deterministic debug description string (used only when debug feature is enabled).
+    let description = describe_items(&items);
 
-        quote! {
-            pub const __CONFIG_DESC: &str = #descriptions;
-        }
-    } else {
-        quote! {}
-    };
-
-    // Now consume items to generate the body
+    // Turn the DSL into statements that mutate `b`.
     let body = to_stmts(items, &core);
 
-    // Generate a unique identifier for this submission
-    let submission_id = format!("__client_defaults_{}", uuid::Uuid::new_v4().simple());
-    let submission_ident = syn::Ident::new(&submission_id, proc_macro2::Span::call_site());
-
-    // Debug output at compile time if enabled
+    // Optional compile-time diagnostics for the macro author (does not affect output).
     if std::env::var("DEBUG_HTTP_INVENTORY").is_ok() {
         eprintln!(
-            "cargo:warning=[HTTP-INVENTORY] Registering config with priority={} from {}",
+            "cargo:warning=[HTTP-INVENTORY] Registering config with priority={} from {}: {}",
             priority,
-            std::env::var("CARGO_PKG_NAME").unwrap_or_else(|_| "unknown".to_string())
+            std::env::var("CARGO_PKG_NAME").unwrap_or_else(|_| "unknown".to_string()),
+            description,
         );
     }
 
-    // Add debug_print_inventory call if the feature is enabled
-    let debug_call = if cfg!(feature = "debug-inventory") {
+    // Debug logging injected into the generated closure, gated by the
+    // *macro crate's* `debug-inventory` feature (checked at expansion time).
+    let debug_block = if cfg!(feature = "debug-inventory") {
         quote! {
-            #config_description
-
-            // Ensure the debug function gets called when config is applied
-            pub fn __cfg_with_debug(
-                b: #core::ReqwestClientBuilder
-            ) -> #core::ReqwestClientBuilder {
-                eprintln!("[HTTP-INVENTORY] Applying: {} (priority={})", __CONFIG_DESC, #priority);
-                __cfg(b)
-            }
+            eprintln!(
+                "[HTTP-INVENTORY] Applying: {} (priority={})",
+                #description,
+                #priority
+            );
         }
     } else {
         quote! {}
     };
 
-    // Use the debug wrapper if feature is enabled
-    let apply_fn = if cfg!(feature = "debug-inventory") {
-        quote! { __cfg_with_debug }
-    } else {
-        quote! { __cfg }
-    };
-
+    // `apply` is a capture-free closure; it will coerce to a fn pointer
+    // if `ConfigRecord::apply` is typed as `fn(ReqwestClientBuilder) -> ReqwestClientBuilder`.
     let out = quote! {
-        #[allow(non_snake_case)]
-        mod #submission_ident {
-            use super::*;
-            #[allow(unused)]
-            pub fn __cfg(
-                mut b: #core::ReqwestClientBuilder
-            ) -> #core::ReqwestClientBuilder {
-                #body
-                b
-            }
-
-            #debug_call
-
-            #core::inventory::submit! {
-                #core::registry::ConfigRecord {
-                    priority: #priority,
-                    apply: #apply_fn,
-                }
+        #core::inventory::submit! {
+            #core::registry::ConfigRecord {
+                priority: #priority,
+                apply: |mut b: #core::ReqwestClientBuilder| {
+                    #debug_block
+                    #body
+                    b
+                },
             }
         }
     };
+
     out.into()
 }

common/http-api-client/src/dns.rs

@@ -3,28 +3,41 @@
 
 //! DNS resolver configuration for internal lookups.
 //!
-//! The resolver itself is the set combination of the google, cloudflare, and quad9 endpoints
-//! supporting DoH and DoT.
+//! The resolver itself is the set combination of the cloudflare, and quad9 endpoints supporting DoH
+//! and DoT.
 //!
-//! This resolver supports a fallback mechanism where, should the DNS-over-TLS resolution fail, a
-//! followup resolution will be done using the hosts configured default (e.g. `/etc/resolve.conf` on
-//! linux). This is disabled by default and can be enabled using [`enable_system_fallback`].
-//!
-//! Requires the `dns-over-https-rustls`, `webpki-roots` feature for the
-//! `hickory-resolver` crate
-//!
-//!
-//! Note: The hickory DoH resolver can cause warning logs about H2 connection failure. This
-//! indicates that the long lived https connection was closed by the remote peer and the resolver
-//! will have to reconnect. It should not impact actual functionality.
-//!
-//! code ref: https://github.com/hickory-dns/hickory-dns/blob/06a8b1ce9bd9322d8e6accf857d30257e1274427/crates/proto/src/h2/h2_client_stream.rs#L534
-//!
-//! example log:
-//!
-//! ```txt
-//!   WARN /home/ubuntu/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hickory-proto-0.24.3/src/h2/h2_client_stream.rs:493: h2 connection failed: unexpected end of file
+//! ```rust
+//! use nym_http_api_client::HickoryDnsResolver;
+//! # use nym_http_api_client::ResolveError;
+//! # type Err = ResolveError;
+//! # async fn run() -> Result<(), Err> {
+//! let resolver = HickoryDnsResolver::default();
+//! resolver.resolve_str("example.com").await?;
+//! # Ok(())
+//! # }
 //! ```
+//!
+//! ## Fallbacks
+//!
+//! **System Resolver --** This resolver supports an optional fallback mechanism where, should the
+//! DNS-over-TLS resolution fail, a followup resolution will be done using the hosts configured
+//! default (e.g. `/etc/resolve.conf` on linux).
+//!
+//! This is disabled by default and can be enabled using `enable_system_fallback`.
+//!
+//! **Static Table --**  There is also a second optional fallback mechanism that allows a static map
+//! to be used as a last resort. This can help when DNS encounters errors due to blocked resolvers
+//! or unknown conditions. This is enabled by default, and can be customized if building a new
+//! resolver.
+//!
+//! ## IPv4 / IPv6
+//!
+//! By default the resolver uses only IPv4 nameservers, and is configured to do `A` lookups first,
+//! and only do `AAAA` if no `A` record is available.
+//!
+//! ---
+//!
+//! Requires the `dns-over-https-rustls`, `webpki-roots` feature for the `hickory-resolver` crate
 #![deny(missing_docs)]
 
 use crate::ClientBuilder;
@@ -39,7 +52,7 @@ use std::{
 
 use hickory_resolver::{
     TokioResolver,
-    config::{LookupIpStrategy, NameServerConfigGroup, ResolverConfig},
+    config::{NameServerConfig, NameServerConfigGroup, ResolverConfig, ResolverOpts},
     lookup_ip::LookupIpIntoIter,
     name_server::TokioConnectionProvider,
 };
@@ -49,7 +62,11 @@ use tracing::*;
 
 mod constants;
 mod static_resolver;
-pub use static_resolver::*;
+pub(crate) use static_resolver::*;
+
+pub(crate) const DEFAULT_POSITIVE_LOOKUP_CACHE_TTL: Duration = Duration::from_secs(1800);
+pub(crate) const DEFAULT_OVERALL_LOOKUP_TIMEOUT: Duration = Duration::from_secs(6);
+pub(crate) const DEFAULT_QUERY_TIMEOUT: Duration = Duration::from_secs(3);
 
 impl ClientBuilder {
     /// Override the DNS resolver implementation used by the underlying http client.
@@ -71,7 +88,10 @@ impl ClientBuilder {
 // but tools like valgrind might report "memory leaks" as it isn't obvious this is intentional.
 static SHARED_RESOLVER: LazyLock<HickoryDnsResolver> = LazyLock::new(|| {
     tracing::debug!("Initializing shared DNS resolver");
-    HickoryDnsResolver::default()
+    HickoryDnsResolver {
+        use_shared: false, // prevent infinite recursion
+        ..Default::default()
+    }
 });
 
 #[derive(Debug, thiserror::Error)]
@@ -111,7 +131,7 @@ pub struct HickoryDnsResolver {
     state: Arc<OnceCell<TokioResolver>>,
     fallback: Option<Arc<OnceCell<TokioResolver>>>,
     static_base: Option<Arc<OnceCell<StaticResolver>>>,
-    dont_use_shared: bool,
+    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,
@@ -122,9 +142,9 @@ impl Default for HickoryDnsResolver {
         Self {
             state: Default::default(),
             fallback: Default::default(),
-            static_base: Default::default(),
-            dont_use_shared: Default::default(),
-            overall_dns_timeout: Duration::from_secs(10),
+            static_base: Some(Default::default()),
+            use_shared: true,
+            overall_dns_timeout: DEFAULT_OVERALL_LOOKUP_TIMEOUT,
         }
     }
 }
@@ -134,7 +154,7 @@ impl Resolve for HickoryDnsResolver {
         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 use_shared = self.use_shared;
         let overall_dns_timeout = self.overall_dns_timeout;
         Box::pin(async move {
             resolve(
@@ -142,7 +162,7 @@ impl Resolve for HickoryDnsResolver {
                 resolver,
                 maybe_fallback,
                 maybe_static,
-                independent,
+                use_shared,
                 overall_dns_timeout,
             )
             .await
@@ -236,7 +256,7 @@ impl HickoryDnsResolver {
             self.state.clone(),
             self.fallback.clone(),
             self.static_base.clone(),
-            self.dont_use_shared,
+            self.use_shared,
             self.overall_dns_timeout,
         )
         .await
@@ -246,25 +266,25 @@ impl HickoryDnsResolver {
     /// Create a (lazy-initialized) resolver that is not shared across threads.
     pub fn thread_resolver() -> Self {
         Self {
-            dont_use_shared: true,
+            use_shared: false,
             ..Default::default()
         }
     }
 
-    fn new_resolver(dont_use_shared: bool) -> Result<TokioResolver, ResolveError> {
+    fn new_resolver(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 {
+        if !use_shared {
             new_resolver()
         } else {
             Ok(SHARED_RESOLVER.state.get_or_try_init(new_resolver)?.clone())
         }
     }
 
-    fn new_resolver_system(dont_use_shared: bool) -> Result<TokioResolver, ResolveError> {
+    fn new_resolver_system(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() {
+        if !use_shared || SHARED_RESOLVER.fallback.is_none() {
             new_resolver_system()
         } else {
             Ok(SHARED_RESOLVER
@@ -276,8 +296,8 @@ impl HickoryDnsResolver {
         }
     }
 
-    fn new_static_fallback(dont_use_shared: bool) -> StaticResolver {
-        if !dont_use_shared && let Some(ref shared_resolver) = SHARED_RESOLVER.static_base {
+    fn new_static_fallback(use_shared: bool) -> StaticResolver {
+        if use_shared && let Some(ref shared_resolver) = SHARED_RESOLVER.static_base {
             shared_resolver
                 .get_or_init(new_default_static_fallback)
                 .clone()
@@ -294,6 +314,11 @@ impl HickoryDnsResolver {
             .as_ref()
             .unwrap()
             .get_or_try_init(new_resolver_system)?;
+
+        // IF THIS INSTANCE IS A FRONT FOR THE SHARED RESOLVER SHOULDN'T THIS FN ENABLE THE SYSTEM FALLBACK FOR THE SHARED RESOLVER TOO?
+        // if self.use_shared {
+        //     SHARED_RESOLVER.enable_system_fallback()?;
+        // }
         Ok(())
     }
 
@@ -301,6 +326,11 @@ impl HickoryDnsResolver {
     /// returned immediately
     pub fn disable_system_fallback(&mut self) {
         self.fallback = None;
+
+        // // IF THIS INSTANCE IS A FRONT FOR THE SHARED RESOLVER SHOULDN'T THIS FN ENABLE THE SYSTEM FALLBACK FOR THE SHARED RESOLVER TOO?
+        // if self.use_shared {
+        //     SHARED_RESOLVER.fallback = None;
+        // }
     }
 
     /// Get the current map of hostname to address in use by the fallback static lookup if one
@@ -316,39 +346,122 @@ impl HickoryDnsResolver {
             .expect("infallible assign");
         self.static_base = Some(Arc::new(cell));
     }
+
+    /// Successfully resolved addresses are cached for a minimum of 30 minutes
+    /// Individual lookup Timeouts are set to 3 seconds
+    /// Number of retries after lookup failure before giving up is set to (default) to 2
+    /// Lookup order is set to (default) A then AAAA
+    /// Number or parallel lookup is set to (default) 2
+    /// Nameserver selection uses the (default) EWMA statistics / performance based strategy
+    fn default_options() -> ResolverOpts {
+        let mut opts = ResolverOpts::default();
+        // Always cache successful responses for queries received by this resolver for 30 min minimum.
+        opts.positive_min_ttl = Some(DEFAULT_POSITIVE_LOOKUP_CACHE_TTL);
+        opts.timeout = DEFAULT_QUERY_TIMEOUT;
+
+        opts
+    }
+
+    /// Get the list of currently available nameserver configs.
+    pub fn all_configured_name_servers(&self) -> Vec<NameServerConfig> {
+        default_nameserver_group().to_vec()
+    }
+
+    /// Get the list of currently used nameserver configs.
+    pub fn active_name_servers(&self) -> Vec<NameServerConfig> {
+        if !self.use_shared {
+            return self
+                .state
+                .get()
+                .map(|r| r.config().name_servers().to_vec())
+                .unwrap_or(self.all_configured_name_servers());
+        }
+
+        SHARED_RESOLVER.active_name_servers()
+    }
+
+    /// Do a trial resolution using each nameserver individually to test which are working and which
+    /// fail to complete a lookup. This will always try the full set of default configured resolvers.
+    pub async fn trial_nameservers(&self) {
+        let nameservers = default_nameserver_group();
+        for (ns, result) in trial_nameservers_inner(&nameservers).await {
+            if let Err(e) = result {
+                warn!("trial {ns:?} errored: {e}");
+            } else {
+                info!("trial {ns:?} succeeded");
+            }
+        }
+    }
 }
 
 /// 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.
 ///
-/// Timeout Defaults to 5 seconds
+/// Individual lookup Timeouts are set to 3 seconds
 /// Number of retries after lookup failure before giving up Defaults to 2
+/// Lookup order is set to (default) A then AAAA
 ///
 /// 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 name_servers = default_nameserver_group_ipv4_only();
 
-    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)
+    Ok(configure_and_build_resolver(name_servers))
 }
 
-fn configure_and_build_resolver(
-    name_servers: NameServerConfigGroup,
-) -> Result<TokioResolver, ResolveError> {
+fn configure_and_build_resolver<G>(name_servers: G) -> TokioResolver
+where
+    G: Into<NameServerConfigGroup>,
+{
+    let options = HickoryDnsResolver::default_options();
+    let name_servers: NameServerConfigGroup = name_servers.into();
+    info!("building new configured resolver");
+    debug!("configuring resolver with {options:?}, {name_servers:?}");
+
     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;
-    // 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));
+    resolver_builder = resolver_builder.with_options(options);
 
-    Ok(resolver_builder.build())
+    resolver_builder.build()
+}
+
+fn filter_ipv4(nameservers: impl AsRef<[NameServerConfig]>) -> Vec<NameServerConfig> {
+    nameservers
+        .as_ref()
+        .iter()
+        .filter(|ns| ns.socket_addr.is_ipv4())
+        .cloned()
+        .collect()
+}
+
+#[allow(unused)]
+fn filter_ipv6(nameservers: impl AsRef<[NameServerConfig]>) -> Vec<NameServerConfig> {
+    nameservers
+        .as_ref()
+        .iter()
+        .filter(|ns| ns.socket_addr.is_ipv6())
+        .cloned()
+        .collect()
+}
+
+#[allow(unused)]
+fn default_nameserver_group() -> NameServerConfigGroup {
+    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());
+    name_servers
+}
+
+fn default_nameserver_group_ipv4_only() -> NameServerConfigGroup {
+    filter_ipv4(&default_nameserver_group() as &[NameServerConfig]).into()
+}
+
+#[allow(unused)]
+fn default_nameserver_group_ipv6_only() -> NameServerConfigGroup {
+    filter_ipv6(&default_nameserver_group() as &[NameServerConfig]).into()
 }
 
 /// Create a new resolver with the default configuration, which reads from the system DNS config
@@ -356,7 +469,12 @@ fn configure_and_build_resolver(
 /// addresses to work with "happy eyeballs" algorithm.
 fn new_resolver_system() -> Result<TokioResolver, ResolveError> {
     let mut resolver_builder = TokioResolver::builder_tokio()?;
-    resolver_builder.options_mut().ip_strategy = LookupIpStrategy::Ipv4AndIpv6;
+
+    let options = HickoryDnsResolver::default_options();
+    info!("building new fallback system resolver");
+    debug!("fallback system resolver with {options:?}");
+
+    resolver_builder = resolver_builder.with_options(options);
 
     Ok(resolver_builder.build())
 }
@@ -365,11 +483,54 @@ fn new_default_static_fallback() -> StaticResolver {
     StaticResolver::new(constants::default_static_addrs())
 }
 
+/// Do a trial resolution using each nameserver individually to test which are working and which
+/// fail to complete a lookup.
+async fn trial_nameservers_inner(
+    name_servers: &[NameServerConfig],
+) -> Vec<(NameServerConfig, Result<(), ResolveError>)> {
+    let mut trial_lookups = tokio::task::JoinSet::new();
+
+    for name_server in name_servers {
+        let ns = name_server.clone();
+        trial_lookups.spawn(async { (ns.clone(), trial_lookup(ns, "example.com").await) });
+    }
+
+    trial_lookups.join_all().await
+}
+
+/// Create an independent resolver that has only the provided nameserver and do one lookup for the
+/// provided query target.
+async fn trial_lookup(name_server: NameServerConfig, query: &str) -> Result<(), ResolveError> {
+    debug!("running ns trial {name_server:?} query={query}");
+
+    let resolver = configure_and_build_resolver(vec![name_server]);
+
+    match tokio::time::timeout(DEFAULT_OVERALL_LOOKUP_TIMEOUT, resolver.ipv4_lookup(query)).await {
+        Ok(Ok(_)) => Ok(()),
+        Ok(Err(e)) => Err(e.into()),
+        Err(_) => Err(ResolveError::Timeout),
+    }
+}
+
 #[cfg(test)]
 mod test {
     use super::*;
     use itertools::Itertools;
     use std::collections::HashMap;
+    use std::{
+        net::{IpAddr, Ipv4Addr, Ipv6Addr},
+        time::Instant,
+    };
+
+    /// 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)),
+    ];
 
     #[tokio::test]
     async fn reqwest_with_custom_dns() {
@@ -428,99 +589,172 @@ mod test {
         assert!(addrs.contains(&example_ip6));
         Ok(())
     }
-}
 
-#[cfg(test)]
-mod failure_test {
-    use super::*;
-    use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+    // Test the nameserver trial functionality with mostly nameservers guaranteed to be broken and
+    // one that should work.
+    #[tokio::test]
+    async fn trial_nameservers() {
+        let good_cf_ip = IpAddr::V4(Ipv4Addr::new(1, 1, 1, 1));
 
-    /// 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)),
-    ];
+        let mut ns_ips = GUARANTEED_BROKEN_IPS_1.to_vec();
+        ns_ips.push(good_cf_ip);
 
-    // 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,
+            &ns_ips,
             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");
+        let inner = configure_and_build_resolver(broken_ns_https);
 
         // 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),
+            use_shared: false,
+            state: Arc::new(OnceCell::with_value(inner)),
             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");
+        let name_servers = resolver.state.get().unwrap().config().name_servers();
+        for (ns, result) in trial_nameservers_inner(name_servers).await {
+            if ns.socket_addr.ip() == good_cf_ip {
+                assert!(result.is_ok())
+            } else {
+                assert!(result.is_err())
+            }
+        }
+    }
 
-        // 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)));
+    mod failure_test {
+        use super::*;
 
-        Ok(())
+        // 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);
+
+            Ok(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 {
+                use_shared: false,
+                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 {
+                use_shared: false,
+                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 static table
+            let domain = "non-existent.nymtech.net";
+            let result = resolver.resolve_str(domain).await;
+            assert!(result.is_err_and(|e| matches!(e, ResolveError::Timeout)));
+
+            Ok(())
+        }
+
+        #[test]
+        fn default_resolver_uses_ipv4_only_nameservers() {
+            let resolver = HickoryDnsResolver::thread_resolver();
+            resolver
+                .active_name_servers()
+                .iter()
+                .all(|cfg| cfg.socket_addr.is_ipv4());
+
+            SHARED_RESOLVER
+                .active_name_servers()
+                .iter()
+                .all(|cfg| cfg.socket_addr.is_ipv4());
+        }
+
+        #[tokio::test]
+        #[ignore]
+        // this test is dependent of external network setup -- i.e. blocking all traffic to the default
+        // resolvers. Otherwise the default resolvers will succeed without using the static fallback,
+        // making the test pointless
+        async fn dns_lookup_failure_on_shared() -> Result<(), ResolveError> {
+            let time_start = 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::default();
+
+            // successful lookup using fallback to static resolver
+            let domain = "rpc.nymtech.net";
+            let _ = resolver
+                .resolve_str(domain)
+                .await
+                .expect("failed to resolve address in static lookup");
+
+            println!(
+                "{}ms resolved {domain}",
+                (Instant::now() - time_start).as_millis()
+            );
+
+            // unsuccessful lookup - primary times out, and not in static table
+            let domain = "non-existent.nymtech.net";
+            let result = resolver.resolve_str(domain).await;
+            assert!(result.is_err());
+            // assert!(result.is_err_and(|e| matches!(e, ResolveError::Timeout)));
+            // assert!(result.is_err_and(|e| matches!(e, ResolveError::ResolveError(e) if e.is_nx_domain())));
+            Ok(())
+        }
     }
 }

common/http-api-client/src/lib.rs

@@ -175,7 +175,7 @@ mod user_agent;
 pub use user_agent::UserAgent;
 
 #[cfg(not(target_arch = "wasm32"))]
-mod dns;
+pub mod dns;
 mod path;
 
 #[cfg(not(target_arch = "wasm32"))]
@@ -895,20 +895,22 @@ impl Client {
         self.retry_limit = limit;
     }
 
+    #[cfg(feature = "tunneling")]
     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()
-            }
+        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()
         }
     }
 
+    #[cfg(not(feature = "tunneling"))]
+    fn matches_current_host(&self, url: &Url) -> bool {
+        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)
     ///
     /// Takes an optional URL argument. If this is none, the current host will be updated automatically.

common/http-api-client/src/tests.rs

@@ -91,7 +91,7 @@ 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 because of DNS (rotate)
+        "http://broken.nym.test".parse()?, // This should fail because of DNS NXDomain (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
     ])?