Add criteria checklist

- add pr validation checklist
fix issues with using the http client using default-features=false (#6281 )
2025-12-15 10:15:29 +01:00 · 2025-12-10 11:54:24 -07:00 · 2025-12-10 16:17:08 +00:00 · 2025-12-10 14:05:16 +01:00 · 2025-12-09 18:45:17 +01:00 · 2025-12-04 15:00:35 +01:00
1445 changed files with 66685 additions and 32815 deletions
@@ -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.
+
@@ -21,7 +21,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        platform: [ arc-ubuntu-22.04 ]
+        platform: [ arc-linux-latest ]

    runs-on: ${{ matrix.platform }}
    env:
@@ -9,7 +9,7 @@ on:

 jobs:
  wasm:
-    runs-on: arc-ubuntu-22.04
+    runs-on: arc-linux-latest
    env:
      CARGO_TERM_COLOR: always
      RUSTUP_PERMIT_COPY_RENAME: 1
@@ -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
@@ -8,10 +8,13 @@ on:
      - 'gateway/**'
      - 'integrations/**'
      - 'nym-api/**'
+      - 'nym-authenticator-client/**'
      - 'nym-credential-proxy/**'
+      - 'nym-ip-packet-client/**'
      - 'nym-network-monitor/**'
      - 'nym-node/**'
      - 'nym-node-status-api/**'
+      - 'nym-registration-client/**'
      - 'nym-statistics-api/**'
      - 'nym-outfox/**'
      - 'nym-validator-rewarder/**'
@@ -81,12 +84,21 @@ jobs:
          command: fmt
          args: --all -- --check

-      - name: Clippy
+      - name: Clippy (macos)
+        if: contains(matrix.os, 'mac')
+        uses: actions-rs/cargo@v1
+        with:
+          command: clippy
+          args: --workspace --all-targets --exclude nym-gateway-probe -- -D warnings
+
+      - name: Clippy (non-macos)
+        if: contains(matrix.os, 'linux') || contains(matrix.os, 'windows')
        uses: actions-rs/cargo@v1
        with:
          command: clippy
          args: --workspace --all-targets -- -D warnings

+
      - name: Build all binaries
        uses: actions-rs/cargo@v1
        with:
@@ -10,13 +10,13 @@ env:

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

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

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

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.47.1
+        uses: mikefarah/yq@v4.48.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml
@@ -11,7 +11,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        platform: [ arc-ubuntu-22.04 ]
+        platform: [ arc-linux-latest-dind ]

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

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

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

      - name: Prepare build output
        shell: bash
@@ -17,7 +17,7 @@ jobs:
  build:
    # since it's going to be compiled into wasm, there's absolutely
    # no point in running CI on different OS-es
-    runs-on: ubuntu-22.04
+    runs-on: arc-linux-latest
    env:
      CARGO_TERM_COLOR: always
      RUSTUP_PERMIT_COPY_RENAME: 1
@@ -54,7 +54,7 @@ jobs:
        uses: actions-rs/cargo@v1
        with:
          command: test
-          args: --lib --manifest-path contracts/Cargo.toml
+          args: --lib --manifest-path contracts/Cargo.toml --all-features

      - name: Check formatting
        uses: actions-rs/cargo@v1
@@ -10,7 +10,7 @@ on:

 jobs:
  build:
-    runs-on: arc-ubuntu-22.04
+    runs-on: arc-linux-latest
    env:
      RUSTUP_PERMIT_COPY_RENAME: 1
    defaults:
@@ -6,16 +6,14 @@ on:
    paths:
      - "ts-packages/**"
      - "sdk/typescript/**"
-      - "nym-connect/desktop/src/**"
-      - "nym-connect/desktop/package.json"
      - "nym-wallet/src/**"
      - "nym-wallet/package.json"
-      - "explorer/**"
+      - "explorer-v2/**"
      - ".github/workflows/ci-lint-typescript.yml"

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

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

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

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

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

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

 jobs:
  build:
-    runs-on: arc-ubuntu-22.04
+    runs-on: arc-linux-latest
    env:
      CARGO_TERM_COLOR: always
      RUSTUP_PERMIT_COPY_RENAME: 1
@@ -8,7 +8,7 @@ on:

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

@@ -4,14 +4,14 @@ on:
  workflow_dispatch:
  pull_request:
    paths:
-      - 'wasm/**'
-      - 'clients/client-core/**'
-      - 'common/**'
-      - '.github/workflows/ci-sdk-wasm.yml'
+      - "wasm/**"
+      - "clients/client-core/**"
+      - "common/**"
+      - ".github/workflows/ci-sdk-wasm.yml"

 jobs:
  wasm:
-    runs-on: arc-ubuntu-22.04
+    runs-on: arc-linux-latest
    env:
      CARGO_TERM_COLOR: always
      RUSTUP_PERMIT_COPY_RENAME: 1
@@ -31,9 +31,9 @@ jobs:
          components: rustfmt, clippy

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

      - name: Install wasm-pack
        run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
@@ -41,7 +41,7 @@ jobs:
      - name: Install wasm-opt
        uses: ./.github/actions/install-wasm-opt
        with:
-          version: '116'
+          version: "116"

      - name: Install wasm-bindgen-cli
        run: cargo install wasm-bindgen-cli
@@ -14,6 +14,6 @@ jobs:
        with:
          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
      - name: SonarQube Scan
-        uses: SonarSource/sonarqube-scan-action@v5
+        uses: SonarSource/sonarqube-scan-action@v6
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
@@ -34,7 +34,7 @@ jobs:
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
        with:
          # Upload entire repository
          path: './ppa'
@@ -8,6 +8,6 @@ jobs:
    steps:
    - uses: actions/first-interaction@v3
      with:
-        repo-token: ${{ secrets.GITHUB_TOKEN }}
-        issue-message: 'Thank you for raising this issue'
-        pr-message: 'Thank you for making this first PR'
+        repo_token: ${{ secrets.GITHUB_TOKEN }}
+        issue_message: 'Thank you for raising this issue'
+        pr_message: 'Thank you for making this first PR'
@@ -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
@@ -21,7 +21,7 @@ jobs:
      fail-fast: false
      matrix:
        include:
-          - os: arc-ubuntu-22.04
+          - os: arc-linux-latest
            target: x86_64-unknown-linux-gnu
    runs-on:  ${{ matrix.os }}

@@ -30,11 +30,13 @@ jobs:
      release_date: ${{ fromJSON(steps.create-release.outputs.assets)[0].published_at }}
      client_hash: ${{ steps.binary-hashes.outputs.client_hash }}
      nymvisor_hash: ${{ steps.binary-hashes.outputs.nymvisor_hash }}
+      nymnode_hash: ${{ steps.binary-hashes.outputs.nymnode_hash }}
      socks5_hash: ${{ steps.binary-hashes.outputs.socks5_hash }}
      netreq_hash: ${{ steps.binary-hashes.outputs.netreq_hash }}
      cli_hash: ${{ steps.binary-hashes.outputs.cli_hash }}
      client_version: ${{ steps.binary-versions.outputs.client_version }}
      nymvisor_version: ${{ steps.binary-versions.outputs.nymvisor_version }}
+      nymnode_version: ${{ steps.binary-versions.outputs.nymnode_version }}
      socks5_version: ${{ steps.binary-versions.outputs.socks5_version }}
      netreq_version: ${{ steps.binary-versions.outputs.netreq_version }}
      cli_version: ${{ steps.binary-versions.outputs.cli_version }}
@@ -74,6 +76,7 @@ jobs:
            target/release/nym-network-requester
            target/release/nym-cli
            target/release/nymvisor
+            target/release/nym-node
          retention-days: 30
    
      - id: create-release
@@ -88,6 +91,7 @@ jobs:
            target/release/nym-network-requester
            target/release/nym-cli
            target/release/nymvisor
+            target/release/nym-node

  push-release-data-client:
    if: ${{ (startsWith(github.ref, 'refs/tags/nym-binaries-') && github.event_name == 'release') || github.event_name == 'workflow_dispatch' }}
@@ -4,7 +4,7 @@ on:

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

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

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

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

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

      - name: Install dependencies
        run: yarn
@@ -8,7 +8,7 @@ env:

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

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

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

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

      - name: Get version from cargo.toml
-        uses: mikefarah/yq@v4.47.1
+        uses: mikefarah/yq@v4.48.1
        id: get_version
        with:
          cmd: yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/nym-network-monitor/Cargo.toml
@@ -3,11 +3,6 @@ name: Build and upload Node Status agent container to harbor.nymte.ch
 on:
  workflow_dispatch:
    inputs:
-      gateway_probe_git_ref:
-        type: string
-        default: nym-vpn-core-v1.4.0
-        required: true
-        description: Which gateway probe git ref to build the image with
      release_image:
        description: 'Tag image as a release'
        required: true
@@ -20,7 +15,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
@@ -43,16 +38,6 @@ jobs:
          VERSION=$(yq -oy '.package.version' ${{ env.WORKING_DIRECTORY }}/Cargo.toml)
          echo "result=$VERSION" >> $GITHUB_OUTPUT

-      - name: cleanup-gateway-probe-ref
-        id: cleanup_gateway_probe_ref
-        run: |
-          GATEWAY_PROBE_GIT_REF=${{ github.event.inputs.gateway_probe_git_ref }}
-          GIT_REF_SLUG="${GATEWAY_PROBE_GIT_REF//\//-}"
-          echo "git_ref=${GIT_REF_SLUG}" >> $GITHUB_OUTPUT
-
-      - name: Set GIT_TAG variable
-        run: echo "GIT_TAG=${{ env.WORKING_DIRECTORY }}-${{ steps.get_version.outputs.result }}-${{ steps.cleanup_gateway_probe_ref.outputs.git_ref }}" >> $GITHUB_ENV
-
      - name: Initialize RELEASE_TAG
        run: echo "RELEASE_TAG=" >> $GITHUB_ENV
      
@@ -61,24 +46,12 @@ jobs:
        run: echo "RELEASE_TAG=golden-" >> $GITHUB_ENV
      
      - name: Set IMAGE_NAME_AND_TAGS variable
-        run: echo "IMAGE_NAME_AND_TAGS=${{ env.CONTAINER_NAME }}:${{ env.RELEASE_TAG }}${{ steps.get_version.outputs.result }}-${{ steps.cleanup_gateway_probe_ref.outputs.git_ref }}" >> $GITHUB_ENV
+        run: echo "IMAGE_NAME_AND_TAGS=${{ env.CONTAINER_NAME }}:${{ env.RELEASE_TAG }}${{ steps.get_version.outputs.result }}" >> $GITHUB_ENV
        
      - name: New env vars
-        run: echo "RELEASE_TAG='$RELEASE_TAG' GIT_TAG='$GIT_TAG' IMAGE_NAME_AND_TAGS='$IMAGE_NAME_AND_TAGS'"        
-
-      # - name: Remove existing tag if exists
-      #   run: |
-      #     if git rev-parse $${{ env.GIT_TAG }} >/dev/null 2>&1; then
-      #       git push --delete origin $${{ env.GIT_TAG }}
-      #       git tag -d $${{ env.GIT_TAG }}
-      #     fi
-
-      # - name: Create tag
-      #   run: |
-      #     git tag -a $${{ env.GIT_TAG }} -m "Version ${{ steps.get_version.outputs.result }}-${{ steps.cleanup_gateway_probe_ref.outputs.git_ref }}"
-      #     git push origin $${{ env.GIT_TAG }}
+        run: echo "RELEASE_TAG='$RELEASE_TAG' IMAGE_NAME_AND_TAGS='$IMAGE_NAME_AND_TAGS'"        

      - name: BuildAndPushImageOnHarbor
        run: |
-          docker build --build-arg GIT_REF=${{ github.event.inputs.gateway_probe_git_ref }} -f ${{ env.WORKING_DIRECTORY }}/Dockerfile . -t harbor.nymte.ch/nym/${{ env.IMAGE_NAME_AND_TAGS }}
+          docker build -f ${{ env.WORKING_DIRECTORY }}/Dockerfile . -t harbor.nymte.ch/nym/${{ env.IMAGE_NAME_AND_TAGS }}
          docker push harbor.nymte.ch/nym/${{ env.CONTAINER_NAME }} --all-tags
@@ -14,7 +14,7 @@ env:

 jobs:
  build-container:
-    runs-on: arc-ubuntu-22.04-dind
+    runs-on: arc-linux-latest-dind
    steps:
      - name: Login to Harbor
        uses: docker/login-action@v3
@@ -69,6 +69,6 @@ jobs:

      - name: BuildAndPushImageOnHarbor
        run: |
-          docker build -f ${{ env.WORKING_DIRECTORY }}/Dockerfile-pg . -t harbor.nymte.ch/nym/${{ env.IMAGE_NAME_AND_TAGS }} -t harbor.nymte.ch/nym/${{ env.CONTAINER_NAME }}:latest
+          docker build -f ${{ env.WORKING_DIRECTORY }}/Dockerfile . -t harbor.nymte.ch/nym/${{ env.IMAGE_NAME_AND_TAGS }} -t harbor.nymte.ch/nym/${{ env.CONTAINER_NAME }}:latest
          docker push harbor.nymte.ch/nym/${{ env.CONTAINER_NAME }} --all-tags

@@ -26,7 +26,7 @@ jobs:
          git config --global user.name "Lawrence Stalder"

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

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

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

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

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

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

 **/settings.sql
 **/enter_db.sh
+
+*.profraw
@@ -4,6 +4,222 @@ Post 1.0.0 release, the changelog format is based on [Keep a Changelog](https://

 ## [Unreleased]

+## [2025.21-mozzarella] (2025-11-25)
+
+- [bugfix] Tunnel not waiting on MixnetClient to shut down cleanly ([#6225])
+- bugfix: fix credential proxy upgrade mode attestation url arg ([#6202])
+- HTTP API resilience enable & domain rotation conditions ([#6200])
+- Remove debug feature from http-macro spec in gateway probe ([#6195])
+- DNS relibility and troubleshooting  ([#6179])
+- [bugfix] Distinguish authenticator errors by credential spent ([#6176])
+- Typescript SDK 1.4.1 ([#6146])
+- Enable URL rotation and retries for mixnet gateway init ([#6126])
+- Feature/credential proxy jwt ([#5957])
+
+[#6225]: https://github.com/nymtech/nym/pull/6225
+[#6202]: https://github.com/nymtech/nym/pull/6202
+[#6200]: https://github.com/nymtech/nym/pull/6200
+[#6195]: https://github.com/nymtech/nym/pull/6195
+[#6179]: https://github.com/nymtech/nym/pull/6179
+[#6176]: https://github.com/nymtech/nym/pull/6176
+[#6146]: https://github.com/nymtech/nym/pull/6146
+[#6126]: https://github.com/nymtech/nym/pull/6126
+[#5957]: https://github.com/nymtech/nym/pull/5957
+
+## [2025.20-leerdammer] (2025-11-12)
+
+- Max/tweak ts sdk actions ([#6185])
+- chore: resolve clippy 1.91 warnings ([#6168])
+- [chore] Remove unused dependencies ([#6151])
+- Use typed-builder for registration client builder config ([#6150])
+- tommy is too quick ([#6149])
+- configurable mixnet client startup timeout ([#6148])
+- [Feature/operators]: QUIC bridge deployment script v2 ([#6145])
+- Bugfix: Add circuit breaker ([#6143])
+- bugfix: update internal owner address in transferred share ([#6139])
+- Update quic_bridge_deployment.sh for IPv4 and .deb package ([#6138])
+- feat: expose more explicit new_with_fronted_urls builder for http API client ([#6136])
+- bugfix: update stored epoch share when changing ownership ([#6135])
+- Domain fronting ([#6134])
+- bugfix: update stored epoch share when changing announce address ([#6131])
+
+[#6185]: https://github.com/nymtech/nym/pull/6185
+[#6168]: https://github.com/nymtech/nym/pull/6168
+[#6151]: https://github.com/nymtech/nym/pull/6151
+[#6150]: https://github.com/nymtech/nym/pull/6150
+[#6149]: https://github.com/nymtech/nym/pull/6149
+[#6148]: https://github.com/nymtech/nym/pull/6148
+[#6145]: https://github.com/nymtech/nym/pull/6145
+[#6143]: https://github.com/nymtech/nym/pull/6143
+[#6139]: https://github.com/nymtech/nym/pull/6139
+[#6138]: https://github.com/nymtech/nym/pull/6138
+[#6136]: https://github.com/nymtech/nym/pull/6136
+[#6135]: https://github.com/nymtech/nym/pull/6135
+[#6134]: https://github.com/nymtech/nym/pull/6134
+[#6131]: https://github.com/nymtech/nym/pull/6131
+
+## [2025.19-kase] (2025-10-30)
+
+- update ns agent workflow ([#6154])
+- Cherry pick - request #6143 from nymtech/bugfix/mix-tx-closed-v2 ([#6153])
+- bugfix: nym-credential-proxy query params parsing regression ([#6121])
+- bugfix: revert some dep updates introduced in #6043 ([#6120])
+- Skip ipv6 metadata endpoint request ([#6118])
+- update to no longer use 1mb files ([#6117])
+- chore: restore pending dkg contract state migration ([#6116])
+- Revert "Propagate cancel token to mixnet client" ([#6115])
+- Update dirs to 6.0 ([#6109])
+- Propagate cancel token to mixnet client ([#6105])
+- bugfix: retrieve and update ticketbook in the same query ([#6101])
+- bugfix: include network name in the default gateway probe config path ([#6100])
+- Bugfix/incompatibility fixes ([#6099])
+- [DOCs/operators] QUIC deployment script & docs ([#6098])
+- bugfix: testnet manager 02sql migration ([#6096])
+- feat: move gateway probe to monorepo (and update to rust edition 2024) ([#6094])
+- bugfix: use custom topology provider for list of init gateways ([#6092])
+- Max/fix wasm client + build commands ([#6043])
+
+[#6154]: https://github.com/nymtech/nym/pull/6154
+[#6153]: https://github.com/nymtech/nym/pull/6153
+[#6121]: https://github.com/nymtech/nym/pull/6121
+[#6120]: https://github.com/nymtech/nym/pull/6120
+[#6118]: https://github.com/nymtech/nym/pull/6118
+[#6117]: https://github.com/nymtech/nym/pull/6117
+[#6116]: https://github.com/nymtech/nym/pull/6116
+[#6115]: https://github.com/nymtech/nym/pull/6115
+[#6109]: https://github.com/nymtech/nym/pull/6109
+[#6105]: https://github.com/nymtech/nym/pull/6105
+[#6101]: https://github.com/nymtech/nym/pull/6101
+[#6100]: https://github.com/nymtech/nym/pull/6100
+[#6099]: https://github.com/nymtech/nym/pull/6099
+[#6098]: https://github.com/nymtech/nym/pull/6098
+[#6096]: https://github.com/nymtech/nym/pull/6096
+[#6094]: https://github.com/nymtech/nym/pull/6094
+[#6092]: https://github.com/nymtech/nym/pull/6092
+[#6043]: https://github.com/nymtech/nym/pull/6043
+
+## [2025.18-jarlsberg] (2025-10-14)
+
+- ns-api: add descriptions to dVPN gateway responses ([#6102])
+- NS API: use new probe download filesize and milliseconds field ([#6097])
+- ns-api: use download files size from probes instead of parsing filenames ([#6095])
+- ns-api: add new fields for probe output for query_metadata and download file size and duration in ms ([#6091])
+- Bugfix/bloomfilters purge ([#6089])
+- Hotfix: Update API source in node ping tester script ([#6082])
+- Get wireguard keypair as arg instead of reading it from disk ([#6078])
+- Feature: Ping probe all nodes /described nodes from a server ([#6074])
+- Node Status API: add bridge information to dVPN endpoint ([#6069])
+- frontdoor typo fix ([#6067])
+- Feature: Node rewards tracker ([#6064])
+- [chore] Clippy fix ([#6060])
+- Registration Client ([#6059])
+- Bugfix: Nym node CLI download nym-node exception ([#6058])
+- Feature: Nym node html landing page ([#6053])
+- feat: DKG contract method for updating announce address ([#6050])
+- feat: NS ticket faucet ([#6047])
+- Bridge proto client params in Self-Described ([#6035])
+- Node Status API: remove sqlite support ([#6004])
+- Benny/ci contract fix ([#5962])
+
+[#6102]: https://github.com/nymtech/nym/pull/6102
+[#6097]: https://github.com/nymtech/nym/pull/6097
+[#6095]: https://github.com/nymtech/nym/pull/6095
+[#6091]: https://github.com/nymtech/nym/pull/6091
+[#6089]: https://github.com/nymtech/nym/pull/6089
+[#6082]: https://github.com/nymtech/nym/pull/6082
+[#6078]: https://github.com/nymtech/nym/pull/6078
+[#6074]: https://github.com/nymtech/nym/pull/6074
+[#6069]: https://github.com/nymtech/nym/pull/6069
+[#6067]: https://github.com/nymtech/nym/pull/6067
+[#6064]: https://github.com/nymtech/nym/pull/6064
+[#6060]: https://github.com/nymtech/nym/pull/6060
+[#6059]: https://github.com/nymtech/nym/pull/6059
+[#6058]: https://github.com/nymtech/nym/pull/6058
+[#6053]: https://github.com/nymtech/nym/pull/6053
+[#6050]: https://github.com/nymtech/nym/pull/6050
+[#6047]: https://github.com/nymtech/nym/pull/6047
+[#6035]: https://github.com/nymtech/nym/pull/6035
+[#6004]: https://github.com/nymtech/nym/pull/6004
+[#5962]: https://github.com/nymtech/nym/pull/5962
+
+## [2025.17-isabirra] (2025-09-29)
+
+- Bugfix | Fix the registration handshake ([#6062])
+- Convenience for ShutdownTracker ([#6038])
+- chore: made http-api-client-macro doctest compile ([#6037])
+- feat: refresh mixnet contract on epoch progression ([#6023])
+- chore: remove legacy nodes from nym api [and kinda-ish from node status api] ([#6021])
+- Feature/credential proxy crate ([#6018])
+- Moving clients crate from vpn-client repo to here ([#6015])
+- Feature/cancellation migration ([#6014])
+- Use default value for the ports until api is deployed ([#6007])
+- bugfix: return from MixTrafficController if client request channel has closed ([#6002])
+- Revert "Create an axum_test client for more integrated unit testing (… ([#5999])
+- chore: upgraded syn to 2.0 and removed nym-execute ([#5998])
+- feat: use `ShutdownToken` (`CancellationToken` inside) for nym-api ([#5997])
+- bugfix: Recipient deserialisation for deserialisers missing bytes specialisation ([#5991])
+- chore: use updated version of simulate endpoint ([#5988])
+- chore: purge temp databases on build ([#5984])
+- Bump sha.js from 2.4.11 to 2.4.12 ([#5983])
+- Feature: Delegation program stake checker and adjuster ([#5980])
+- build(deps): bump actions/setup-java from 4 to 5 ([#5975])
+- Domain fronting integration ([#5974])
+- chore: internal hidden command to force advance nyx epoch ([#5964])
+- Create an axum_test client for more integrated unit testing ([#5956])
+- feat: shared library for attempting to retrieve update mode attestation ([#5954])
+- Bump slab from 0.4.10 to 0.4.11 ([#5952])
+- build(deps): bump actions/first-interaction from 1 to 3 ([#5950])
+- fix: use WASM compatible time API in client ([#5948])
+- feat: credential proxy deposit pool ([#5945])
+- build(deps): bump actions/download-artifact from 4 to 5 ([#5939])
+- feat: nym signers monitor ([#5933])
+- Bump console from 0.15.11 to 0.16.0 ([#5931])
+- Bump mock_instant from 0.5.3 to 0.6.0 ([#5930])
+- Bump tokio from 1.46.1 to 1.47.1 ([#5929])
+- Bump defguard_wireguard_rs from v0.4.7 to v0.7.5 ([#5928])
+- Bump indicatif from 0.17.11 to 0.18.0 ([#5924])
+- Feature: Nym node autorun CLI ([#5916])
+- build(deps): bump mikefarah/yq from 4.45.4 to 4.47.1 ([#5911])
+- build(deps): bump pbkdf2 from 3.1.2 to 3.1.3 ([#5869])
+
+[#6062]: https://github.com/nymtech/nym/pull/6062
+[#6038]: https://github.com/nymtech/nym/pull/6038
+[#6037]: https://github.com/nymtech/nym/pull/6037
+[#6023]: https://github.com/nymtech/nym/pull/6023
+[#6021]: https://github.com/nymtech/nym/pull/6021
+[#6018]: https://github.com/nymtech/nym/pull/6018
+[#6015]: https://github.com/nymtech/nym/pull/6015
+[#6014]: https://github.com/nymtech/nym/pull/6014
+[#6007]: https://github.com/nymtech/nym/pull/6007
+[#6002]: https://github.com/nymtech/nym/pull/6002
+[#5999]: https://github.com/nymtech/nym/pull/5999
+[#5998]: https://github.com/nymtech/nym/pull/5998
+[#5997]: https://github.com/nymtech/nym/pull/5997
+[#5991]: https://github.com/nymtech/nym/pull/5991
+[#5988]: https://github.com/nymtech/nym/pull/5988
+[#5984]: https://github.com/nymtech/nym/pull/5984
+[#5983]: https://github.com/nymtech/nym/pull/5983
+[#5980]: https://github.com/nymtech/nym/pull/5980
+[#5975]: https://github.com/nymtech/nym/pull/5975
+[#5974]: https://github.com/nymtech/nym/pull/5974
+[#5964]: https://github.com/nymtech/nym/pull/5964
+[#5956]: https://github.com/nymtech/nym/pull/5956
+[#5954]: https://github.com/nymtech/nym/pull/5954
+[#5952]: https://github.com/nymtech/nym/pull/5952
+[#5950]: https://github.com/nymtech/nym/pull/5950
+[#5948]: https://github.com/nymtech/nym/pull/5948
+[#5945]: https://github.com/nymtech/nym/pull/5945
+[#5939]: https://github.com/nymtech/nym/pull/5939
+[#5933]: https://github.com/nymtech/nym/pull/5933
+[#5931]: https://github.com/nymtech/nym/pull/5931
+[#5930]: https://github.com/nymtech/nym/pull/5930
+[#5929]: https://github.com/nymtech/nym/pull/5929
+[#5928]: https://github.com/nymtech/nym/pull/5928
+[#5924]: https://github.com/nymtech/nym/pull/5924
+[#5916]: https://github.com/nymtech/nym/pull/5916
+[#5911]: https://github.com/nymtech/nym/pull/5911
+[#5869]: https://github.com/nymtech/nym/pull/5869
+
 ## [2025.16-halloumi] (2025-09-16)

 - Backport metadata endpoint ([#6010])
@@ -31,6 +31,7 @@ members = [
    "common/client-libs/mixnet-client",
    "common/client-libs/validator-client",
    "common/commands",
+    "common/nym-common",
    "common/config",
    "common/cosmwasm-smart-contracts/coconut-dkg",
    "common/cosmwasm-smart-contracts/contracts-common",
@@ -58,7 +59,8 @@ members = [
    "common/gateway-requests",
    "common/gateway-stats-storage",
    "common/gateway-storage",
-    "common/http-api-client", "common/http-api-client-macro",
+    "common/http-api-client",
+    "common/http-api-client-macro",
    "common/http-api-common",
    "common/inclusion-probability",
    "common/ip-packet-requests",
@@ -67,6 +69,8 @@ members = [
    "common/network-defaults",
    "common/node-tester-utils",
    "common/nonexhaustive-delayqueue",
+    "common/nym-cache",
+    "common/nym-connection-monitor",
    "common/nym-id",
    "common/nym-metrics",
    "common/nym_offline_compact_ecash",
@@ -83,8 +87,11 @@ 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",
    "common/service-provider-requests-common",
    "common/socks5-client-core",
@@ -92,11 +99,13 @@ members = [
    "common/socks5/requests",
    "common/statistics",
    "common/store-cipher",
-    "common/task", "common/test-utils",
+    "common/task",
+    "common/test-utils",
    "common/ticketbooks-merkle",
    "common/topology",
    "common/tun",
-    "common/types", "common/upgrade-mode-check",
+    "common/types",
+    "common/upgrade-mode-check",
    "common/verloc",
    "common/wasm/client-core",
    "common/wasm/storage",
@@ -117,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",
@@ -125,10 +135,11 @@ members = [
    "nym-node-status-api/nym-node-status-client",
    "nym-node/nym-node-metrics",
    "nym-node/nym-node-requests",
-    "nym-outfox", "nym-signers-monitor",
+    "nym-outfox",
+    "nym-registration-client",
+    "nym-signers-monitor",
    "nym-statistics-api",
    "nym-validator-rewarder",
-    "nym-wg-gateway-client",
    "nyx-chain-watcher",
    "sdk/ffi/cpp",
    "sdk/ffi/go",
@@ -142,10 +153,9 @@ members = [
    "tools/internal/contract-state-importer/importer-cli",
    "tools/internal/contract-state-importer/importer-contract",
    "tools/internal/mixnet-connectivity-check",
-    # "tools/internal/sdk-version-bump",
+#    "tools/internal/sdk-version-bump",
    "tools/internal/ssl-inject",
    "tools/internal/testnet-manager",
-    "tools/internal/testnet-manager",
    "tools/internal/testnet-manager/dkg-bypass-contract",
    "tools/internal/validator-status-check",
    "tools/nym-cli",
@@ -158,11 +168,13 @@ members = [
    "wasm/mix-fetch",
    "wasm/node-tester",
    "wasm/zknym-lib",
+    "nym-gateway-probe"
 ]

 default-members = [
    "clients/native",
    "clients/socks5",
+    "nym-authenticator-client",
    "nym-api",
    "nym-credential-proxy/nym-credential-proxy",
    "nym-node",
@@ -176,16 +188,16 @@ default-members = [
    "tools/nymvisor",
 ]

-exclude = ["explorer", "contracts", "nym-wallet", "cpu-cycles"]
+exclude = ["contracts", "nym-wallet", "cpu-cycles"]

 [workspace.package]
 authors = ["Nym Technologies SA"]
 repository = "https://github.com/nymtech/nym"
 homepage = "https://nymtech.net"
 documentation = "https://nymtech.net"
-edition = "2021"
+edition = "2024"
 license = "Apache-2.0"
-rust-version = "1.81"
+rust-version = "1.85"
 readme = "README.md"

 [workspace.dependencies]
@@ -207,7 +219,6 @@ base64 = "0.22.1"
 base85rs = "0.1.3"
 bincode = "1.3.3"
 bip39 = { version = "2.0.0", features = ["zeroize"] }
-bit-vec = "0.7.0"                                     # can we unify those?
 bitvec = "1.0.0"
 blake3 = "1.7.0"
 bloomfilter = "3.0.1"
@@ -235,13 +246,11 @@ criterion = "0.5"
 csv = "1.3.1"
 ctr = "0.9.1"
 cupid = "0.6.1"
-curve25519-dalek = "4.1"
 dashmap = "5.5.3"
 # We want https://github.com/DefGuard/wireguard-rs/pull/64 , but there's no crates.io release being pushed out anymore
 defguard_wireguard_rs = { git = "https://github.com/DefGuard/wireguard-rs.git", rev = "v0.4.7" }
 digest = "0.10.7"
-dirs = "5.0"
-doc-comment = "0.3"
+dirs = "6.0"
 dotenvy = "0.15.6"
 dyn-clone = "1.0.19"
 ecdsa = "0.16"
@@ -257,12 +266,10 @@ futures = "0.3.31"
 futures-util = "0.3"
 generic-array = "0.14.7"
 getrandom = "0.2.10"
-getset = "0.1.5"
+glob = "0.3"
 handlebars = "3.5.5"
-headers = "0.4.0"
 hex = "0.4.3"
-hex-literal = "0.3.3"
-hickory-resolver = "0.25"
+hickory-resolver = "0.25.2"
 hkdf = "0.12.3"
 hmac = "0.12.1"
 http = "1"
@@ -285,12 +292,10 @@ lazy_static = "1.5.0"
 ledger-transport = "0.10.0"
 ledger-transport-hid = "0.10.0"
 log = "0.4"
-maxminddb = "0.23.0"
 mime = "0.3.17"
 moka = { version = "0.12", features = ["future"] }
 nix = "0.27.1"
 notify = "5.1.0"
-okapi = "0.7.0"
 once_cell = "1.21.3"
 opentelemetry = "0.19.0"
 opentelemetry-jaeger = "0.18.0"
@@ -298,7 +303,7 @@ parking_lot = "0.12.3"
 pem = "0.8"
 petgraph = "0.6.5"
 pin-project = "1.1"
-pin-project-lite = "0.2.16"
+pnet_packet = "0.35.0"
 publicsuffix = "2.3.0"
 proc_pidinfo = "0.1.3"
 quote = "1"
@@ -306,13 +311,10 @@ rand = "0.8.5"
 rand_chacha = "0.3"
 rand_core = "0.6.3"
 rand_distr = "0.4"
-rand_pcg = "0.3.1"
-rand_seeder = "0.2.3"
 rayon = "1.5.1"
 regex = "1.10.6"
 reqwest = { version = "0.12.15", default-features = false }
 rs_merkle = "1.5.0"
-safer-ffi = "0.1.13"
 schemars = "0.8.22"
 semver = "1.0.26"
 serde = "1.0.219"
@@ -349,15 +351,17 @@ tokio-tungstenite = { version = "0.20.1" }
 tokio-util = "0.7.15"
 toml = "0.8.22"
 tower = "0.5.2"
-tower-http = "0.5.2"
+tower-http = "0.6.6"
 tracing = "0.1.41"
 tracing-log = "0.2"
 tracing-opentelemetry = "0.19.0"
-tracing-subscriber = "0.3.19"
+tracing-subscriber = "0.3.20"
 tracing-tree = "0.2.2"
 tracing-indicatif = "0.3.9"
+tracing-test = "0.2.5"
 ts-rs = "10.1.0"
 tungstenite = { version = "0.20.1", default-features = false }
+typed-builder = "0.23.0"
 uniffi = "0.29.2"
 uniffi_build = "0.29.0"
 url = "2.5"
@@ -366,6 +370,7 @@ utoipa-swagger-ui = "8.1"
 utoipauto = "0.2"
 uuid = "*"
 vergen = { version = "=8.3.1", default-features = false }
+vergen-gitcl = { version = "1.0.8", default-features = false }
 walkdir = "2"
 x25519-dalek = "2.0.0"
 zeroize = "1.7.0"
@@ -397,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 }
@@ -405,18 +412,19 @@ prost = { version = "0.13", default-features = false }
 # wasm-related dependencies
 gloo-utils = "0.2.0"
 gloo-net = "0.6.0"
+gloo-timers = "0.3.0"

 indexed_db_futures = "0.6.4"
 js-sys = "0.3.76"
 serde-wasm-bindgen = "0.6.5"
 tsify = "0.4.5"
+tokio_with_wasm = { version = "0.8.7" }
 wasm-bindgen = "0.2.99"
 wasm-bindgen-futures = "0.4.49"
 wasm-bindgen-test = "0.3.49"
 wasmtimer = "0.4.1"
 web-sys = "0.3.76"

-
 # for local development:
 #[patch.crates-io]
 #sphinx-packet = { path = "../sphinx" }
@@ -452,6 +460,11 @@ opt-level = 'z'
 unexpected_cfgs = { level = "warn", check-cfg = ['cfg(tokio_unstable)'] }

 [workspace.lints.clippy]
+suspicious = "deny"
+complexity = "deny"
+perf = "deny"
+style = "deny"
+
 unwrap_used = "deny"
 expect_used = "deny"
 todo = "deny"
@@ -109,7 +109,7 @@ sdk-wasm-build:
 	$(MAKE) -C wasm/node-tester
 	$(MAKE) -C wasm/mix-fetch
 	$(MAKE) -C wasm/zknym-lib
-	#$(MAKE) -C wasm/full-nym-wasm
+	# $(MAKE) -C wasm/full-nym-wasm

 # run this from npm/yarn to ensure tools are in the path, e.g. yarn build:sdk from root of repo
 sdk-typescript-build:
@@ -154,6 +154,7 @@ CONTRACTS_OUT_DIR = contracts/artifacts
 #
 COSMWASM_OPTIMIZER_IMAGE ?= cosmwasm/optimizer:0.17.0
 COSMWASM_OPTIMIZER_PLATFORM ?= linux/amd64
+COSMWASM_CHECK_IMAGE ?= rust:1.88

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

+# Check artifacts with cosmwasm-check inside the optimizer image
+docker-check-contracts:
+	@docker run --rm --platform $(COSMWASM_OPTIMIZER_PLATFORM) \
+	  -v $(CURDIR):/code --workdir /code \
+	  --entrypoint /bin/sh \
+	  $(COSMWASM_CHECK_IMAGE) -lc 'apt-get update && apt-get install -y --no-install-recommends llvm-dev libclang-dev pkg-config && export PATH="/usr/local/cargo/bin:/usr/local/rustup/bin:$$PATH" && cargo install cosmwasm-check --locked && WASMER_ENGINE=universal WASMER_COMPILER=singlepass cosmwasm-check contracts/artifacts/*.wasm'
+
 wasm-opt-contracts:
 	@for WASM in $(WASM_CONTRACT_DIR)/*.wasm; do \
 	  echo "Running wasm-opt on $$WASM"; \
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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>
@@ -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;
+    }
+}
@@ -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;
+    }
+}
@@ -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 }
@@ -0,0 +1 @@
+#!/bin/bash
@@ -0,0 +1,3 @@
+- name: Reload systemd
+  systemd:
+    daemon_reload: yes
@@ -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
@@ -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
@@ -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"
@@ -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
@@ -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
@@ -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 }}"
@@ -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
@@ -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 }}"
@@ -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
@@ -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
@@ -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
+
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1,10 +1,10 @@
 [package]
 name = "nym-client"
-version = "1.1.62"
+version = "1.1.67"
 authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
 description = "Implementation of the Nym Client"
 edition = "2021"
-rust-version = "1.70"
+rust-version = "1.85"
 license.workspace = true

 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
@@ -60,6 +60,7 @@ impl SocketClient {
        let ClientInput {
            connection_command_sender,
            input_sender,
+            ..
        } = client_input;

        let ClientOutput {
@@ -1,10 +1,10 @@
 [package]
 name = "nym-socks5-client"
-version = "1.1.62"
+version = "1.1.67"
 authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>"]
 description = "A SOCKS5 localhost proxy that converts incoming messages to Sphinx and sends them to a Nym address"
 edition = "2021"
-rust-version = "1.70"
+rust-version = "1.85"
 license.workspace = true

 [dependencies]
@@ -1,8 +1,8 @@
 // Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use futures::channel::mpsc;
 use futures::StreamExt;
+use futures::channel::mpsc;
 use notify::event::{DataChange, MetadataKind, ModifyKind};
 use notify::{Config, Event, EventKind, RecommendedWatcher, RecursiveMode, Watcher};
 use std::collections::HashMap;
@@ -96,10 +96,10 @@ impl AsyncFileWatcher {
        // when testing I was consistently getting two `Modify(Data(Any))` events in quick succession
        // (probably to modify content and metadata).
        // we really only want to propagate one of them
-        if let Some(previous) = self.last_received.get(&event.kind) {
-            if now.duration_since(*previous) < self.tick_duration {
-                return false;
-            }
+        if let Some(previous) = self.last_received.get(&event.kind)
+            && now.duration_since(*previous) < self.tick_duration
+        {
+            return false;
        }

        let Some(filters) = &self.filters else {
@@ -13,7 +13,10 @@ base64 = { workspace = true }
 bincode = { workspace = true }
 rand = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
+semver = { workspace = true }
+strum_macros = { workspace = true }
 thiserror = { workspace = true }
+tracing = { workspace = true }

 nym-credentials-interface = { path = "../credentials-interface" }
 nym-crypto = { path = "../crypto", features = ["asymmetric"] }
@@ -27,7 +30,13 @@ hmac = { workspace = true, optional = true }
 sha2 = { workspace = true, optional = true }
 x25519-dalek = { workspace = true, features = ["static_secrets"] }

+[dev-dependencies]
+nym-test-utils = { path = "../test-utils" }
+
 [features]
 default = ["verify"]
 # this is moved to a separate feature as we really need clients to import it (especially, *cough*, wasm)
 verify = ["hmac", "sha2"]
+
+[lints]
+workspace = true
@@ -0,0 +1,372 @@
+// Copyright 2025 Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+use nym_sphinx::addressing::Recipient;
+use nym_wireguard_types::PeerPublicKey;
+
+use crate::{
+    AuthenticatorVersion, Error,
+    traits::{
+        FinalMessage, InitMessage, QueryBandwidthMessage, TopUpMessage, UpgradeModeMessage,
+        Versionable,
+    },
+    v2, v3, v4, v5, v6,
+};
+
+// This is very redundant with AuthenticatorRequest and I reckon they could be smooshed.
+// It is a bit out of scope for me at the moment though
+#[derive(Debug)]
+pub enum ClientMessage {
+    Initial(Box<dyn InitMessage + Send + Sync + 'static>),
+    Final(Box<dyn FinalMessage + Send + Sync + 'static>),
+    Query(Box<dyn QueryBandwidthMessage + Send + Sync + 'static>),
+    TopUp(Box<dyn TopUpMessage + Send + Sync + 'static>),
+    UpgradeModeCheck(Box<dyn UpgradeModeMessage + Send + Sync + 'static>),
+}
+
+pub struct SerialisedRequest {
+    pub bytes: Vec<u8>,
+    pub request_id: u64,
+}
+
+impl SerialisedRequest {
+    pub fn new(bytes: Vec<u8>, request_id: u64) -> Self {
+        Self { bytes, request_id }
+    }
+}
+
+impl ClientMessage {
+    fn serialise_v1(&self) -> Result<SerialisedRequest, Error> {
+        Err(Error::UnsupportedVersion)
+    }
+
+    fn serialise_v2(&self, reply_to: Recipient) -> Result<SerialisedRequest, Error> {
+        use v2::{
+            registration::{ClientMac, FinalMessage, GatewayClient, InitMessage},
+            request::AuthenticatorRequest,
+        };
+        match self {
+            ClientMessage::Initial(init_message) => {
+                let (req, id) = AuthenticatorRequest::new_initial_request(
+                    InitMessage {
+                        pub_key: init_message.pub_key(),
+                    },
+                    reply_to,
+                );
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::Final(final_message) => {
+                let (req, id) = AuthenticatorRequest::new_final_request(
+                    FinalMessage {
+                        gateway_client: GatewayClient {
+                            pub_key: final_message.gateway_client_pub_key(),
+                            private_ip: final_message
+                                .gateway_client_ipv4()
+                                .ok_or(Error::UnsupportedMessage)?
+                                .into(),
+                            mac: ClientMac::new(final_message.gateway_client_mac()),
+                        },
+                        credential: final_message
+                            .credential()
+                            .and_then(|c| c.credential.into_zk_nym())
+                            .map(|c| *c),
+                    },
+                    reply_to,
+                );
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::Query(query_message) => {
+                let (req, id) =
+                    AuthenticatorRequest::new_query_request(query_message.pub_key(), reply_to);
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            _ => Err(Error::UnsupportedMessage),
+        }
+    }
+
+    fn serialise_v3(&self, reply_to: Recipient) -> Result<SerialisedRequest, Error> {
+        use v3::{
+            registration::{ClientMac, FinalMessage, GatewayClient, InitMessage},
+            request::AuthenticatorRequest,
+            topup::TopUpMessage,
+        };
+        match self {
+            ClientMessage::Initial(init_message) => {
+                let (req, id) = AuthenticatorRequest::new_initial_request(
+                    InitMessage {
+                        pub_key: init_message.pub_key(),
+                    },
+                    reply_to,
+                );
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::Final(final_message) => {
+                let (req, id) = AuthenticatorRequest::new_final_request(
+                    FinalMessage {
+                        gateway_client: GatewayClient {
+                            pub_key: final_message.gateway_client_pub_key(),
+                            private_ip: final_message
+                                .gateway_client_ipv4()
+                                .ok_or(Error::UnsupportedMessage)?
+                                .into(),
+                            mac: ClientMac::new(final_message.gateway_client_mac()),
+                        },
+                        credential: final_message
+                            .credential()
+                            .and_then(|c| c.credential.into_zk_nym())
+                            .map(|c| *c),
+                    },
+                    reply_to,
+                );
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::Query(query_message) => {
+                let (req, id) =
+                    AuthenticatorRequest::new_query_request(query_message.pub_key(), reply_to);
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::TopUp(top_up_message) => {
+                let (req, id) = AuthenticatorRequest::new_topup_request(
+                    TopUpMessage {
+                        pub_key: top_up_message.pub_key(),
+                        credential: top_up_message.credential(),
+                    },
+                    reply_to,
+                );
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            _ => Err(Error::UnsupportedMessage),
+        }
+    }
+
+    fn serialise_v4(&self, reply_to: Recipient) -> Result<SerialisedRequest, Error> {
+        use v4::{
+            registration::{ClientMac, FinalMessage, GatewayClient, InitMessage, IpPair},
+            request::AuthenticatorRequest,
+            topup::TopUpMessage,
+        };
+        match self {
+            ClientMessage::Initial(init_message) => {
+                let (req, id) = AuthenticatorRequest::new_initial_request(
+                    InitMessage {
+                        pub_key: init_message.pub_key(),
+                    },
+                    reply_to,
+                );
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::Final(final_message) => {
+                let (req, id) = AuthenticatorRequest::new_final_request(
+                    FinalMessage {
+                        gateway_client: GatewayClient {
+                            pub_key: final_message.gateway_client_pub_key(),
+                            private_ips: IpPair {
+                                ipv4: final_message
+                                    .gateway_client_ipv4()
+                                    .ok_or(Error::UnsupportedMessage)?,
+                                ipv6: final_message
+                                    .gateway_client_ipv6()
+                                    .ok_or(Error::UnsupportedMessage)?,
+                            },
+                            mac: ClientMac::new(final_message.gateway_client_mac()),
+                        },
+                        credential: final_message
+                            .credential()
+                            .and_then(|c| c.credential.into_zk_nym())
+                            .map(|c| *c),
+                    },
+                    reply_to,
+                );
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::Query(query_message) => {
+                let (req, id) =
+                    AuthenticatorRequest::new_query_request(query_message.pub_key(), reply_to);
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::TopUp(top_up_message) => {
+                let (req, id) = AuthenticatorRequest::new_topup_request(
+                    TopUpMessage {
+                        pub_key: top_up_message.pub_key(),
+                        credential: top_up_message.credential(),
+                    },
+                    reply_to,
+                );
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            _ => Err(Error::UnsupportedMessage),
+        }
+    }
+
+    fn serialise_v5(&self) -> Result<SerialisedRequest, Error> {
+        use v5::{
+            registration::{ClientMac, FinalMessage, GatewayClient, InitMessage, IpPair},
+            request::AuthenticatorRequest,
+            topup::TopUpMessage,
+        };
+        match self {
+            ClientMessage::Initial(init_message) => {
+                let (req, id) = AuthenticatorRequest::new_initial_request(InitMessage {
+                    pub_key: init_message.pub_key(),
+                });
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::Final(final_message) => {
+                let (req, id) = AuthenticatorRequest::new_final_request(FinalMessage {
+                    gateway_client: GatewayClient {
+                        pub_key: final_message.gateway_client_pub_key(),
+                        private_ips: IpPair {
+                            ipv4: final_message
+                                .gateway_client_ipv4()
+                                .ok_or(Error::UnsupportedMessage)?,
+                            ipv6: final_message
+                                .gateway_client_ipv6()
+                                .ok_or(Error::UnsupportedMessage)?,
+                        },
+                        mac: ClientMac::new(final_message.gateway_client_mac()),
+                    },
+                    credential: final_message
+                        .credential()
+                        .and_then(|c| c.credential.into_zk_nym())
+                        .map(|c| *c),
+                });
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::Query(query_message) => {
+                let (req, id) = AuthenticatorRequest::new_query_request(query_message.pub_key());
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::TopUp(top_up_message) => {
+                let (req, id) = AuthenticatorRequest::new_topup_request(TopUpMessage {
+                    pub_key: top_up_message.pub_key(),
+                    credential: top_up_message.credential(),
+                });
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            _ => Err(Error::UnsupportedMessage),
+        }
+    }
+
+    fn serialise_v6(&self) -> Result<SerialisedRequest, Error> {
+        use v6::{
+            registration::{ClientMac, FinalMessage, GatewayClient, InitMessage, IpPair},
+            request::AuthenticatorRequest,
+            topup::TopUpMessage,
+            upgrade_mode_check::UpgradeModeCheckRequest,
+        };
+        match self {
+            ClientMessage::Initial(init_message) => {
+                let (req, id) = AuthenticatorRequest::new_initial_request(InitMessage {
+                    pub_key: init_message.pub_key(),
+                });
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::Final(final_message) => {
+                let (req, id) = AuthenticatorRequest::new_final_request(FinalMessage {
+                    gateway_client: GatewayClient {
+                        pub_key: final_message.gateway_client_pub_key(),
+                        private_ips: IpPair {
+                            ipv4: final_message
+                                .gateway_client_ipv4()
+                                .ok_or(Error::UnsupportedMessage)?,
+                            ipv6: final_message
+                                .gateway_client_ipv6()
+                                .ok_or(Error::UnsupportedMessage)?,
+                        },
+                        mac: ClientMac::new(final_message.gateway_client_mac()),
+                    },
+                    credential: final_message.credential(),
+                });
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::Query(query_message) => {
+                let (req, id) = AuthenticatorRequest::new_query_request(query_message.pub_key());
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::TopUp(top_up_message) => {
+                let (req, id) = AuthenticatorRequest::new_topup_request(TopUpMessage {
+                    pub_key: top_up_message.pub_key(),
+                    credential: top_up_message.credential(),
+                });
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+            ClientMessage::UpgradeModeCheck(upgrade_mode_check) => {
+                // currently JWT is the only emergency credential option
+                let Some(upgrade_mode_jwt) =
+                    upgrade_mode_check.upgrade_mode_global_attestation_jwt()
+                else {
+                    return Err(Error::conversion(
+                        "no valid known upgrade mode check variants",
+                    ));
+                };
+                let msg = UpgradeModeCheckRequest::UpgradeModeJwt {
+                    token: upgrade_mode_jwt,
+                };
+
+                let (req, id) = AuthenticatorRequest::new_upgrade_mode_check_request(msg);
+                Ok(SerialisedRequest::new(req.to_bytes()?, id))
+            }
+        }
+    }
+}
+
+impl ClientMessage {
+    // check if message is wasteful e.g. contains a credential
+    pub fn is_wasteful(&self) -> bool {
+        match self {
+            Self::Final(msg) => msg.credential().is_some(),
+            Self::TopUp(_) => true,
+            Self::Initial(_) | Self::Query(_) | Self::UpgradeModeCheck(_) => false,
+        }
+    }
+
+    fn version(&self) -> AuthenticatorVersion {
+        match self {
+            ClientMessage::Initial(msg) => msg.version(),
+            ClientMessage::Final(msg) => msg.version(),
+            ClientMessage::Query(msg) => msg.version(),
+            ClientMessage::TopUp(msg) => msg.version(),
+            ClientMessage::UpgradeModeCheck(msg) => msg.version(),
+        }
+    }
+
+    pub fn bytes(&self, reply_to: Recipient) -> Result<SerialisedRequest, Error> {
+        match self.version() {
+            AuthenticatorVersion::V1 => self.serialise_v1(),
+            AuthenticatorVersion::V2 => self.serialise_v2(reply_to),
+            AuthenticatorVersion::V3 => self.serialise_v3(reply_to),
+            AuthenticatorVersion::V4 => self.serialise_v4(reply_to),
+            AuthenticatorVersion::V5 => self.serialise_v5(),
+            AuthenticatorVersion::V6 => self.serialise_v6(),
+            AuthenticatorVersion::UNKNOWN => Err(Error::UnknownVersion),
+        }
+    }
+
+    pub fn use_surbs(&self) -> bool {
+        use AuthenticatorVersion::*;
+        match self.version() {
+            V1 | V2 | V3 | V4 => false,
+            V5 | V6 => true,
+            UNKNOWN => true,
+        }
+    }
+}
+
+// Same comment as above struct
+#[derive(Debug)]
+pub struct QueryMessageImpl {
+    pub pub_key: PeerPublicKey,
+    pub version: AuthenticatorVersion,
+}
+
+impl Versionable for QueryMessageImpl {
+    fn version(&self) -> AuthenticatorVersion {
+        self.version
+    }
+}
+
+impl QueryBandwidthMessage for QueryMessageImpl {
+    fn pub_key(&self) -> PeerPublicKey {
+        self.pub_key
+    }
+}
@@ -1,6 +1,7 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+use std::fmt::Display;
 use thiserror::Error;

 #[derive(Debug, Error)]
@@ -23,6 +24,27 @@ pub enum Error {
    #[error("conversion: {0}")]
    Conversion(String),

-    #[error("failed to serialize response packet: {source}")]
-    FailedToSerializeResponsePacket { source: Box<bincode::ErrorKind> },
+    // TODO add version number for debugging
+    #[error("unknown version number")]
+    UnknownVersion,
+
+    // TODO add version number for debugging
+    #[error("unsupported request version")]
+    UnsupportedVersion,
+
+    #[error("gateway doesn't support this type of message")]
+    UnsupportedMessage,
+
+    #[error(transparent)]
+    Bincode(#[from] bincode::Error),
+}
+
+impl Error {
+    pub fn conversion(msg: impl Into<String>) -> Self {
+        Error::Conversion(msg.into())
+    }
+
+    pub fn conversion_display(msg: impl Display) -> Self {
+        Error::Conversion(msg.to_string())
+    }
 }
@@ -1,20 +1,27 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+pub mod client_message;
+pub mod models;
+pub mod request;
+pub mod response;
 pub mod traits;
 pub mod v1;
 pub mod v2;
 pub mod v3;
 pub mod v4;
 pub mod v5;
+pub mod v6;

 mod error;
 mod util;
+mod version;

 pub use error::Error;
-pub use v5 as latest;
+pub use v6 as latest;
+pub use version::AuthenticatorVersion;

-pub const CURRENT_VERSION: u8 = 5;
+pub const CURRENT_VERSION: u8 = latest::VERSION;

 fn make_bincode_serializer() -> impl bincode::Options {
    use bincode::Options;
@@ -0,0 +1,58 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_credentials_interface::{
+    BandwidthCredential, CredentialSpendingData, TicketType, UnknownTicketType,
+};
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq)]
+pub enum CurrentUpgradeModeStatus {
+    Enabled,
+    Disabled,
+    // everything pre-v6
+    Unknown,
+}
+
+impl CurrentUpgradeModeStatus {
+    pub fn is_enabled(&self) -> bool {
+        matches!(self, CurrentUpgradeModeStatus::Enabled)
+    }
+}
+
+impl From<bool> for CurrentUpgradeModeStatus {
+    fn from(value: bool) -> Self {
+        if value {
+            CurrentUpgradeModeStatus::Enabled
+        } else {
+            CurrentUpgradeModeStatus::Disabled
+        }
+    }
+}
+
+impl From<CurrentUpgradeModeStatus> for Option<bool> {
+    fn from(value: CurrentUpgradeModeStatus) -> Self {
+        match value {
+            CurrentUpgradeModeStatus::Enabled => Some(true),
+            CurrentUpgradeModeStatus::Disabled => Some(false),
+            CurrentUpgradeModeStatus::Unknown => None,
+        }
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct BandwidthClaim {
+    pub credential: BandwidthCredential,
+    pub kind: TicketType,
+}
+
+impl TryFrom<CredentialSpendingData> for BandwidthClaim {
+    type Error = UnknownTicketType;
+
+    fn try_from(credential: CredentialSpendingData) -> Result<Self, Self::Error> {
+        Ok(BandwidthClaim {
+            kind: TicketType::try_from_encoded(credential.payment.t_type)?,
+            credential: BandwidthCredential::from(credential),
+        })
+    }
+}
@@ -0,0 +1,253 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+use nym_sphinx::addressing::Recipient;
+
+use crate::traits::{
+    FinalMessage, InitMessage, QueryBandwidthMessage, TopUpMessage, UpgradeModeMessage,
+};
+use crate::{v1, v2, v3, v4, v5, v6};
+
+#[derive(Debug)]
+pub enum AuthenticatorRequest {
+    Initial {
+        msg: Box<dyn InitMessage + Send + Sync + 'static>,
+        protocol: Protocol,
+        reply_to: Option<Recipient>,
+        request_id: u64,
+    },
+    Final {
+        msg: Box<dyn FinalMessage + Send + Sync + 'static>,
+        protocol: Protocol,
+        reply_to: Option<Recipient>,
+        request_id: u64,
+    },
+    QueryBandwidth {
+        msg: Box<dyn QueryBandwidthMessage + Send + Sync + 'static>,
+        protocol: Protocol,
+        reply_to: Option<Recipient>,
+        request_id: u64,
+    },
+    TopUpBandwidth {
+        msg: Box<dyn TopUpMessage + Send + Sync + 'static>,
+        protocol: Protocol,
+        reply_to: Option<Recipient>,
+        request_id: u64,
+    },
+    CheckUpgradeMode {
+        msg: Box<dyn UpgradeModeMessage + Send + Sync + 'static>,
+        protocol: Protocol,
+        request_id: u64,
+    },
+}
+
+impl From<v1::request::AuthenticatorRequest> for AuthenticatorRequest {
+    fn from(value: v1::request::AuthenticatorRequest) -> Self {
+        match value.data {
+            v1::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
+                msg: Box::new(init_message),
+                protocol: Protocol {
+                    version: value.version,
+                    service_provider_type: ServiceProviderType::Authenticator,
+                },
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v1::request::AuthenticatorRequestData::Final(gateway_client) => Self::Final {
+                msg: Box::new(gateway_client),
+                protocol: Protocol {
+                    version: value.version,
+                    service_provider_type: ServiceProviderType::Authenticator,
+                },
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v1::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
+                Self::QueryBandwidth {
+                    msg: Box::new(peer_public_key),
+                    protocol: Protocol {
+                        version: value.version,
+                        service_provider_type: ServiceProviderType::Authenticator,
+                    },
+                    reply_to: Some(value.reply_to),
+                    request_id: value.request_id,
+                }
+            }
+        }
+    }
+}
+
+impl From<v2::request::AuthenticatorRequest> for AuthenticatorRequest {
+    fn from(value: v2::request::AuthenticatorRequest) -> Self {
+        match value.data {
+            v2::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
+                msg: Box::new(init_message),
+                protocol: value.protocol,
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v2::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
+                msg: final_message,
+                protocol: value.protocol,
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v2::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
+                Self::QueryBandwidth {
+                    msg: Box::new(peer_public_key),
+                    protocol: value.protocol,
+                    reply_to: Some(value.reply_to),
+                    request_id: value.request_id,
+                }
+            }
+        }
+    }
+}
+
+impl From<v3::request::AuthenticatorRequest> for AuthenticatorRequest {
+    fn from(value: v3::request::AuthenticatorRequest) -> Self {
+        match value.data {
+            v3::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
+                msg: Box::new(init_message),
+                protocol: value.protocol,
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v3::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
+                msg: final_message,
+                protocol: value.protocol,
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v3::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
+                Self::QueryBandwidth {
+                    msg: Box::new(peer_public_key),
+                    protocol: value.protocol,
+                    reply_to: Some(value.reply_to),
+                    request_id: value.request_id,
+                }
+            }
+            v3::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message) => {
+                Self::TopUpBandwidth {
+                    msg: top_up_message,
+                    protocol: value.protocol,
+                    reply_to: Some(value.reply_to),
+                    request_id: value.request_id,
+                }
+            }
+        }
+    }
+}
+
+impl From<v4::request::AuthenticatorRequest> for AuthenticatorRequest {
+    fn from(value: v4::request::AuthenticatorRequest) -> Self {
+        match value.data {
+            v4::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
+                msg: Box::new(init_message),
+                protocol: value.protocol,
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v4::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
+                msg: final_message,
+                protocol: value.protocol,
+                reply_to: Some(value.reply_to),
+                request_id: value.request_id,
+            },
+            v4::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
+                Self::QueryBandwidth {
+                    msg: Box::new(peer_public_key),
+                    protocol: value.protocol,
+                    reply_to: Some(value.reply_to),
+                    request_id: value.request_id,
+                }
+            }
+            v4::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message) => {
+                Self::TopUpBandwidth {
+                    msg: top_up_message,
+                    protocol: value.protocol,
+                    reply_to: Some(value.reply_to),
+                    request_id: value.request_id,
+                }
+            }
+        }
+    }
+}
+
+impl From<v5::request::AuthenticatorRequest> for AuthenticatorRequest {
+    fn from(value: v5::request::AuthenticatorRequest) -> Self {
+        match value.data {
+            v5::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
+                msg: Box::new(init_message),
+                protocol: value.protocol,
+                reply_to: None,
+                request_id: value.request_id,
+            },
+            v5::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
+                msg: final_message,
+                protocol: value.protocol,
+                reply_to: None,
+                request_id: value.request_id,
+            },
+            v5::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
+                Self::QueryBandwidth {
+                    msg: Box::new(peer_public_key),
+                    protocol: value.protocol,
+                    reply_to: None,
+                    request_id: value.request_id,
+                }
+            }
+            v5::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message) => {
+                Self::TopUpBandwidth {
+                    msg: top_up_message,
+                    protocol: value.protocol,
+                    reply_to: None,
+                    request_id: value.request_id,
+                }
+            }
+        }
+    }
+}
+
+impl From<v6::request::AuthenticatorRequest> for AuthenticatorRequest {
+    fn from(value: v6::request::AuthenticatorRequest) -> Self {
+        match value.data {
+            v6::request::AuthenticatorRequestData::Initial(init_message) => Self::Initial {
+                msg: Box::new(init_message),
+                protocol: value.protocol,
+                reply_to: None,
+                request_id: value.request_id,
+            },
+            v6::request::AuthenticatorRequestData::Final(final_message) => Self::Final {
+                msg: final_message,
+                protocol: value.protocol,
+                reply_to: None,
+                request_id: value.request_id,
+            },
+            v6::request::AuthenticatorRequestData::QueryBandwidth(peer_public_key) => {
+                Self::QueryBandwidth {
+                    msg: Box::new(peer_public_key),
+                    protocol: value.protocol,
+                    reply_to: None,
+                    request_id: value.request_id,
+                }
+            }
+            v6::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message) => {
+                Self::TopUpBandwidth {
+                    msg: top_up_message,
+                    protocol: value.protocol,
+                    reply_to: None,
+                    request_id: value.request_id,
+                }
+            }
+            v6::request::AuthenticatorRequestData::CheckUpgradeMode(upgrade_mode_check_msg) => {
+                Self::CheckUpgradeMode {
+                    msg: Box::new(upgrade_mode_check_msg),
+                    protocol: value.protocol,
+                    request_id: value.request_id,
+                }
+            }
+        }
+    }
+}
@@ -0,0 +1,153 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::models::CurrentUpgradeModeStatus;
+use crate::traits::{
+    Id, PendingRegistrationResponse, RegisteredResponse, RemainingBandwidthResponse,
+    TopUpBandwidthResponse, UpgradeModeStatus,
+};
+use crate::{v2, v3, v4, v5, v6};
+
+#[derive(Debug)]
+pub enum AuthenticatorResponse {
+    PendingRegistration(Box<dyn PendingRegistrationResponse + Send + Sync + 'static>),
+    Registered(Box<dyn RegisteredResponse + Send + Sync + 'static>),
+    RemainingBandwidth(Box<dyn RemainingBandwidthResponse + Send + Sync + 'static>),
+    TopUpBandwidth(Box<dyn TopUpBandwidthResponse + Send + Sync + 'static>),
+    UpgradeMode(Box<dyn UpgradeModeStatus + Send + Sync + 'static>),
+}
+
+impl UpgradeModeStatus for AuthenticatorResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        match self {
+            AuthenticatorResponse::PendingRegistration(pending_registration_response) => {
+                pending_registration_response.upgrade_mode_status()
+            }
+            AuthenticatorResponse::Registered(registered_response) => {
+                registered_response.upgrade_mode_status()
+            }
+            AuthenticatorResponse::RemainingBandwidth(remaining_bandwidth_response) => {
+                remaining_bandwidth_response.upgrade_mode_status()
+            }
+            AuthenticatorResponse::TopUpBandwidth(top_up_bandwidth_response) => {
+                top_up_bandwidth_response.upgrade_mode_status()
+            }
+            AuthenticatorResponse::UpgradeMode(upgrade_mode_response) => {
+                upgrade_mode_response.upgrade_mode_status()
+            }
+        }
+    }
+}
+
+impl Id for AuthenticatorResponse {
+    fn id(&self) -> u64 {
+        match self {
+            AuthenticatorResponse::PendingRegistration(pending_registration_response) => {
+                pending_registration_response.id()
+            }
+            AuthenticatorResponse::Registered(registered_response) => registered_response.id(),
+            AuthenticatorResponse::RemainingBandwidth(remaining_bandwidth_response) => {
+                remaining_bandwidth_response.id()
+            }
+            AuthenticatorResponse::TopUpBandwidth(top_up_bandwidth_response) => {
+                top_up_bandwidth_response.id()
+            }
+            AuthenticatorResponse::UpgradeMode(upgrade_mode_response) => upgrade_mode_response.id(),
+        }
+    }
+}
+
+impl From<v2::response::AuthenticatorResponse> for AuthenticatorResponse {
+    fn from(value: v2::response::AuthenticatorResponse) -> Self {
+        match value.data {
+            v2::response::AuthenticatorResponseData::PendingRegistration(
+                pending_registration_response,
+            ) => Self::PendingRegistration(Box::new(pending_registration_response)),
+            v2::response::AuthenticatorResponseData::Registered(registered_response) => {
+                Self::Registered(Box::new(registered_response))
+            }
+            v2::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response,
+            ) => Self::RemainingBandwidth(Box::new(remaining_bandwidth_response)),
+        }
+    }
+}
+
+impl From<v3::response::AuthenticatorResponse> for AuthenticatorResponse {
+    fn from(value: v3::response::AuthenticatorResponse) -> Self {
+        match value.data {
+            v3::response::AuthenticatorResponseData::PendingRegistration(
+                pending_registration_response,
+            ) => Self::PendingRegistration(Box::new(pending_registration_response)),
+            v3::response::AuthenticatorResponseData::Registered(registered_response) => {
+                Self::Registered(Box::new(registered_response))
+            }
+            v3::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response,
+            ) => Self::RemainingBandwidth(Box::new(remaining_bandwidth_response)),
+            v3::response::AuthenticatorResponseData::TopUpBandwidth(top_up_bandwidth_response) => {
+                Self::TopUpBandwidth(Box::new(top_up_bandwidth_response))
+            }
+        }
+    }
+}
+
+impl From<v4::response::AuthenticatorResponse> for AuthenticatorResponse {
+    fn from(value: v4::response::AuthenticatorResponse) -> Self {
+        match value.data {
+            v4::response::AuthenticatorResponseData::PendingRegistration(
+                pending_registration_response,
+            ) => Self::PendingRegistration(Box::new(pending_registration_response)),
+            v4::response::AuthenticatorResponseData::Registered(registered_response) => {
+                Self::Registered(Box::new(registered_response))
+            }
+            v4::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response,
+            ) => Self::RemainingBandwidth(Box::new(remaining_bandwidth_response)),
+            v4::response::AuthenticatorResponseData::TopUpBandwidth(top_up_bandwidth_response) => {
+                Self::TopUpBandwidth(Box::new(top_up_bandwidth_response))
+            }
+        }
+    }
+}
+
+impl From<v5::response::AuthenticatorResponse> for AuthenticatorResponse {
+    fn from(value: v5::response::AuthenticatorResponse) -> Self {
+        match value.data {
+            v5::response::AuthenticatorResponseData::PendingRegistration(
+                pending_registration_response,
+            ) => Self::PendingRegistration(Box::new(pending_registration_response)),
+            v5::response::AuthenticatorResponseData::Registered(registered_response) => {
+                Self::Registered(Box::new(registered_response))
+            }
+            v5::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response,
+            ) => Self::RemainingBandwidth(Box::new(remaining_bandwidth_response)),
+            v5::response::AuthenticatorResponseData::TopUpBandwidth(top_up_bandwidth_response) => {
+                Self::TopUpBandwidth(Box::new(top_up_bandwidth_response))
+            }
+        }
+    }
+}
+
+impl From<v6::response::AuthenticatorResponse> for AuthenticatorResponse {
+    fn from(value: v6::response::AuthenticatorResponse) -> Self {
+        match value.data {
+            v6::response::AuthenticatorResponseData::PendingRegistration(
+                pending_registration_response,
+            ) => Self::PendingRegistration(Box::new(pending_registration_response)),
+            v6::response::AuthenticatorResponseData::Registered(registered_response) => {
+                Self::Registered(Box::new(registered_response))
+            }
+            v6::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response,
+            ) => Self::RemainingBandwidth(Box::new(remaining_bandwidth_response)),
+            v6::response::AuthenticatorResponseData::TopUpBandwidth(top_up_bandwidth_response) => {
+                Self::TopUpBandwidth(Box::new(top_up_bandwidth_response))
+            }
+            v6::response::AuthenticatorResponseData::UpgradeMode(upgrade_mode_check_response) => {
+                Self::UpgradeMode(Box::new(upgrade_mode_check_response))
+            }
+        }
+    }
+}
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::error::Error;
-use base64::{engine::general_purpose, Engine};
+use base64::{Engine, engine::general_purpose};
 use nym_wireguard_types::PeerPublicKey;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
@@ -48,7 +48,7 @@ pub struct RegistrationData {
 }

 #[derive(Serialize, Deserialize, Debug, Clone)]
-pub struct RegistredData {
+pub struct RegisteredData {
    pub pub_key: PeerPublicKey,
    pub private_ip: IpAddr,
    pub wg_port: u16,
@@ -1,7 +1,7 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use super::registration::{RegistrationData, RegistredData, RemainingBandwidthData};
+use super::registration::{RegisteredData, RegistrationData, RemainingBandwidthData};
 use nym_sphinx::addressing::Recipient;
 use serde::{Deserialize, Serialize};

@@ -34,7 +34,7 @@ impl AuthenticatorResponse {
    }

    pub fn new_registered(
-        registred_data: RegistredData,
+        registred_data: RegisteredData,
        reply_to: Recipient,
        request_id: u64,
    ) -> Self {
@@ -108,7 +108,7 @@ pub struct PendingRegistrationResponse {
 pub struct RegisteredResponse {
    pub request_id: u64,
    pub reply_to: Recipient,
-    pub reply: RegistredData,
+    pub reply: RegisteredData,
 }

 #[derive(Clone, Debug, Serialize, Deserialize)]
@@ -154,8 +154,8 @@ impl From<v2::registration::RegistrationData> for v1::registration::Registration
    }
 }

-impl From<v2::registration::RegistredData> for v1::registration::RegistredData {
-    fn from(value: v2::registration::RegistredData) -> Self {
+impl From<v2::registration::RegisteredData> for v1::registration::RegisteredData {
+    fn from(value: v2::registration::RegisteredData) -> Self {
        Self {
            pub_key: value.pub_key,
            private_ip: value.private_ip,
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::error::Error;
-use base64::{engine::general_purpose, Engine};
+use base64::{Engine, engine::general_purpose};
 use nym_credentials_interface::CredentialSpendingData;
 use nym_wireguard_types::PeerPublicKey;
 use serde::{Deserialize, Serialize};
@@ -58,7 +58,7 @@ pub struct RegistrationData {
 }

 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
-pub struct RegistredData {
+pub struct RegisteredData {
    pub pub_key: PeerPublicKey,
    pub private_ip: IpAddr,
    pub wg_port: u16,
@@ -1,7 +1,7 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use super::registration::{RegistrationData, RegistredData, RemainingBandwidthData};
+use super::registration::{RegisteredData, RegistrationData, RemainingBandwidthData};
 use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
 use nym_sphinx::addressing::Recipient;
 use serde::{Deserialize, Serialize};
@@ -38,7 +38,7 @@ impl AuthenticatorResponse {
    }

    pub fn new_registered(
-        registred_data: RegistredData,
+        registred_data: RegisteredData,
        reply_to: Recipient,
        request_id: u64,
    ) -> Self {
@@ -118,7 +118,7 @@ pub struct PendingRegistrationResponse {
 pub struct RegisteredResponse {
    pub request_id: u64,
    pub reply_to: Recipient,
-    pub reply: RegistredData,
+    pub reply: RegisteredData,
 }

 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
@@ -299,8 +299,8 @@ impl From<v2::registration::RegistrationData> for v3::registration::Registration
    }
 }

-impl From<v3::registration::RegistredData> for v2::registration::RegistredData {
-    fn from(value: v3::registration::RegistredData) -> Self {
+impl From<v3::registration::RegisteredData> for v2::registration::RegisteredData {
+    fn from(value: v3::registration::RegisteredData) -> Self {
        Self {
            pub_key: value.pub_key,
            private_ip: value.private_ip,
@@ -309,8 +309,8 @@ impl From<v3::registration::RegistredData> for v2::registration::RegistredData {
    }
 }

-impl From<v2::registration::RegistredData> for v3::registration::RegistredData {
-    fn from(value: v2::registration::RegistredData) -> Self {
+impl From<v2::registration::RegisteredData> for v3::registration::RegisteredData {
+    fn from(value: v2::registration::RegisteredData) -> Self {
        Self {
            pub_key: value.pub_key,
            private_ip: value.private_ip,
@@ -674,7 +674,7 @@ mod tests {
        let pub_key = PeerPublicKey::new(PublicKey::from([0; 32]));
        let private_ip = IpAddr::from_str("10.10.10.10").unwrap();
        let wg_port = 51822;
-        let registred_data = v2::registration::RegistredData {
+        let registred_data = v2::registration::RegisteredData {
            pub_key,
            private_ip,
            wg_port,
@@ -701,7 +701,7 @@ mod tests {
            v3::response::AuthenticatorResponseData::Registered(v3::response::RegisteredResponse {
                request_id,
                reply_to,
-                reply: v3::registration::RegistredData {
+                reply: v3::registration::RegisteredData {
                    wg_port,
                    pub_key,
                    private_ip
@@ -715,7 +715,7 @@ mod tests {
        let pub_key = PeerPublicKey::new(PublicKey::from([0; 32]));
        let private_ip = IpAddr::from_str("10.10.10.10").unwrap();
        let wg_port = 51822;
-        let registred_data = v3::registration::RegistredData {
+        let registred_data = v3::registration::RegisteredData {
            pub_key,
            private_ip,
            wg_port,
@@ -742,7 +742,7 @@ mod tests {
            v2::response::AuthenticatorResponseData::Registered(v2::response::RegisteredResponse {
                request_id,
                reply_to,
-                reply: v2::registration::RegistredData {
+                reply: v2::registration::RegisteredData {
                    wg_port,
                    pub_key,
                    private_ip
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::error::Error;
-use base64::{engine::general_purpose, Engine};
+use base64::{Engine, engine::general_purpose};
 use nym_credentials_interface::CredentialSpendingData;
 use nym_wireguard_types::PeerPublicKey;
 use serde::{Deserialize, Serialize};
@@ -58,7 +58,7 @@ pub struct RegistrationData {
 }

 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
-pub struct RegistredData {
+pub struct RegisteredData {
    pub pub_key: PeerPublicKey,
    pub private_ip: IpAddr,
    pub wg_port: u16,
@@ -1,7 +1,7 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use super::registration::{RegistrationData, RegistredData, RemainingBandwidthData};
+use super::registration::{RegisteredData, RegistrationData, RemainingBandwidthData};
 use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
 use nym_sphinx::addressing::Recipient;
 use serde::{Deserialize, Serialize};
@@ -38,7 +38,7 @@ impl AuthenticatorResponse {
    }

    pub fn new_registered(
-        registred_data: RegistredData,
+        registred_data: RegisteredData,
        reply_to: Recipient,
        request_id: u64,
    ) -> Self {
@@ -139,7 +139,7 @@ pub struct PendingRegistrationResponse {
 pub struct RegisteredResponse {
    pub request_id: u64,
    pub reply_to: Recipient,
-    pub reply: RegistredData,
+    pub reply: RegisteredData,
 }

 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
@@ -262,8 +262,8 @@ impl From<v4::response::TopUpBandwidthResponse> for v3::response::TopUpBandwidth
    }
 }

-impl From<v3::registration::RegistredData> for v4::registration::RegistredData {
-    fn from(value: v3::registration::RegistredData) -> Self {
+impl From<v3::registration::RegisteredData> for v4::registration::RegisteredData {
+    fn from(value: v3::registration::RegisteredData) -> Self {
        Self {
            pub_key: value.pub_key,
            private_ips: value.private_ip.into(),
@@ -272,8 +272,8 @@ impl From<v3::registration::RegistredData> for v4::registration::RegistredData {
    }
 }

-impl From<v4::registration::RegistredData> for v3::registration::RegistredData {
-    fn from(value: v4::registration::RegistredData) -> Self {
+impl From<v4::registration::RegisteredData> for v3::registration::RegisteredData {
+    fn from(value: v4::registration::RegisteredData) -> Self {
        Self {
            pub_key: value.pub_key,
            private_ip: value.private_ips.ipv4.into(),
@@ -565,7 +565,7 @@ mod tests {
        let private_ips =
            v4::registration::IpPair::new(ipv4, Ipv6Addr::from_str("fc01::a0a").unwrap());
        let wg_port = 51822;
-        let registred_data = v3::registration::RegistredData {
+        let registred_data = v3::registration::RegisteredData {
            pub_key,
            private_ip: ipv4.into(),
            wg_port,
@@ -592,7 +592,7 @@ mod tests {
            v4::response::AuthenticatorResponseData::Registered(v4::response::RegisteredResponse {
                request_id,
                reply_to,
-                reply: v4::registration::RegistredData {
+                reply: v4::registration::RegisteredData {
                    wg_port,
                    pub_key,
                    private_ips
@@ -608,7 +608,7 @@ mod tests {
        let private_ips =
            v4::registration::IpPair::new(ipv4, Ipv6Addr::from_str("fc01::10").unwrap());
        let wg_port = 51822;
-        let registred_data = v4::registration::RegistredData {
+        let registred_data = v4::registration::RegisteredData {
            pub_key,
            private_ips,
            wg_port,
@@ -635,7 +635,7 @@ mod tests {
            v3::response::AuthenticatorResponseData::Registered(v3::response::RegisteredResponse {
                request_id,
                reply_to,
-                reply: v3::registration::RegistredData {
+                reply: v3::registration::RegisteredData {
                    wg_port,
                    pub_key,
                    private_ip: ipv4.into()
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::error::Error;
-use base64::{engine::general_purpose, Engine};
+use base64::{Engine, engine::general_purpose};
 use nym_credentials_interface::CredentialSpendingData;
 use nym_network_defaults::constants::{WG_TUN_DEVICE_IP_ADDRESS_V4, WG_TUN_DEVICE_IP_ADDRESS_V6};
 use nym_wireguard_types::PeerPublicKey;
@@ -110,7 +110,7 @@ pub struct RegistrationData {
 }

 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
-pub struct RegistredData {
+pub struct RegisteredData {
    pub pub_key: PeerPublicKey,
    pub private_ips: IpPair,
    pub wg_port: u16,
@@ -1,7 +1,7 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use super::registration::{RegistrationData, RegistredData, RemainingBandwidthData};
+use super::registration::{RegisteredData, RegistrationData, RemainingBandwidthData};
 use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
 use nym_sphinx::addressing::Recipient;
 use serde::{Deserialize, Serialize};
@@ -38,7 +38,7 @@ impl AuthenticatorResponse {
    }

    pub fn new_registered(
-        registred_data: RegistredData,
+        registred_data: RegisteredData,
        reply_to: Recipient,
        request_id: u64,
    ) -> Self {
@@ -139,7 +139,7 @@ pub struct PendingRegistrationResponse {
 pub struct RegisteredResponse {
    pub request_id: u64,
    pub reply_to: Recipient,
-    pub reply: RegistredData,
+    pub reply: RegisteredData,
 }

 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
@@ -186,8 +186,8 @@ impl From<v4::response::TopUpBandwidthResponse> for v5::response::TopUpBandwidth
    }
 }

-impl From<v4::registration::RegistredData> for v5::registration::RegistredData {
-    fn from(value: v4::registration::RegistredData) -> Self {
+impl From<v4::registration::RegisteredData> for v5::registration::RegisteredData {
+    fn from(value: v4::registration::RegisteredData) -> Self {
        Self {
            pub_key: value.pub_key,
            private_ips: value.private_ips.into(),
@@ -405,7 +405,7 @@ mod tests {
        let ipv6 = Ipv6Addr::from_str("fc01::a0a").unwrap();
        let private_ips = v4::registration::IpPair::new(ipv4, ipv6);
        let wg_port = 51822;
-        let registred_data = v4::registration::RegistredData {
+        let registred_data = v4::registration::RegisteredData {
            pub_key,
            private_ips,
            wg_port,
@@ -431,7 +431,7 @@ mod tests {
            upgraded_msg.data,
            v5::response::AuthenticatorResponseData::Registered(v5::response::RegisteredResponse {
                request_id,
-                reply: v5::registration::RegistredData {
+                reply: v5::registration::RegisteredData {
                    wg_port,
                    pub_key,
                    private_ips: v5::registration::IpPair::new(ipv4, ipv6)
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::error::Error;
-use base64::{engine::general_purpose, Engine};
+use base64::{Engine, engine::general_purpose};
 use nym_credentials_interface::CredentialSpendingData;
 use nym_network_defaults::constants::{WG_TUN_DEVICE_IP_ADDRESS_V4, WG_TUN_DEVICE_IP_ADDRESS_V6};
 use nym_wireguard_types::PeerPublicKey;
@@ -108,7 +108,7 @@ pub struct RegistrationData {
 }

 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
-pub struct RegistredData {
+pub struct RegisteredData {
    pub pub_key: PeerPublicKey,
    pub private_ips: IpPair,
    pub wg_port: u16,
@@ -1,7 +1,7 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use super::registration::{RegistrationData, RegistredData, RemainingBandwidthData};
+use super::registration::{RegisteredData, RegistrationData, RemainingBandwidthData};
 use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
 use serde::{Deserialize, Serialize};

@@ -32,7 +32,7 @@ impl AuthenticatorResponse {
        }
    }

-    pub fn new_registered(registred_data: RegistredData, request_id: u64) -> Self {
+    pub fn new_registered(registred_data: RegisteredData, request_id: u64) -> Self {
        Self {
            protocol: Protocol {
                service_provider_type: ServiceProviderType::Authenticator,
@@ -116,7 +116,7 @@ pub struct PendingRegistrationResponse {
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 pub struct RegisteredResponse {
    pub request_id: u64,
-    pub reply: RegistredData,
+    pub reply: RegisteredData,
 }

 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
@@ -0,0 +1,441 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{v5, v6};
+
+impl TryFrom<v5::request::AuthenticatorRequest> for v6::request::AuthenticatorRequest {
+    type Error = crate::Error;
+
+    fn try_from(
+        authenticator_request: v5::request::AuthenticatorRequest,
+    ) -> Result<Self, Self::Error> {
+        Ok(Self {
+            protocol: v6::PROTOCOL,
+            data: authenticator_request.data.try_into()?,
+            request_id: authenticator_request.request_id,
+        })
+    }
+}
+
+impl TryFrom<v5::request::AuthenticatorRequestData> for v6::request::AuthenticatorRequestData {
+    type Error = crate::Error;
+
+    fn try_from(
+        authenticator_request_data: v5::request::AuthenticatorRequestData,
+    ) -> Result<Self, Self::Error> {
+        match authenticator_request_data {
+            v5::request::AuthenticatorRequestData::Initial(init_msg) => Ok(
+                v6::request::AuthenticatorRequestData::Initial(init_msg.into()),
+            ),
+            v5::request::AuthenticatorRequestData::Final(final_msg) => Ok(
+                v6::request::AuthenticatorRequestData::Final(Box::new((*final_msg).try_into()?)),
+            ),
+            v5::request::AuthenticatorRequestData::QueryBandwidth(pub_key) => Ok(
+                v6::request::AuthenticatorRequestData::QueryBandwidth(pub_key),
+            ),
+            v5::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message) => Ok(
+                v6::request::AuthenticatorRequestData::TopUpBandwidth(top_up_message.into()),
+            ),
+        }
+    }
+}
+
+impl From<v5::registration::InitMessage> for v6::registration::InitMessage {
+    fn from(init_msg: v5::registration::InitMessage) -> Self {
+        Self {
+            pub_key: init_msg.pub_key,
+        }
+    }
+}
+
+impl TryFrom<v5::registration::FinalMessage> for v6::registration::FinalMessage {
+    type Error = crate::Error;
+
+    fn try_from(final_msg: v5::registration::FinalMessage) -> Result<Self, Self::Error> {
+        Ok(Self {
+            gateway_client: final_msg.gateway_client.into(),
+            credential: final_msg
+                .credential
+                .map(TryInto::try_into)
+                .transpose()
+                .map_err(Self::Error::conversion_display)?,
+        })
+    }
+}
+
+impl From<v5::registration::GatewayClient> for v6::registration::GatewayClient {
+    fn from(gateway_client: v5::registration::GatewayClient) -> Self {
+        Self {
+            pub_key: gateway_client.pub_key,
+            private_ips: gateway_client.private_ips.into(),
+            mac: gateway_client.mac.into(),
+        }
+    }
+}
+
+impl From<v6::registration::GatewayClient> for v5::registration::GatewayClient {
+    fn from(gateway_client: v6::registration::GatewayClient) -> Self {
+        Self {
+            pub_key: gateway_client.pub_key,
+            private_ips: gateway_client.private_ips.into(),
+            mac: gateway_client.mac.into(),
+        }
+    }
+}
+
+impl From<v5::registration::ClientMac> for v6::registration::ClientMac {
+    fn from(client_mac: v5::registration::ClientMac) -> Self {
+        Self::new((*client_mac).clone())
+    }
+}
+
+impl From<v6::registration::ClientMac> for v5::registration::ClientMac {
+    fn from(client_mac: v6::registration::ClientMac) -> Self {
+        Self::new((*client_mac).clone())
+    }
+}
+
+impl From<Box<v5::topup::TopUpMessage>> for Box<v6::topup::TopUpMessage> {
+    fn from(top_up_message: Box<v5::topup::TopUpMessage>) -> Self {
+        Box::new(v6::topup::TopUpMessage {
+            pub_key: top_up_message.pub_key,
+            credential: top_up_message.credential,
+        })
+    }
+}
+
+impl From<v5::response::AuthenticatorResponse> for v6::response::AuthenticatorResponse {
+    fn from(value: v5::response::AuthenticatorResponse) -> Self {
+        Self {
+            protocol: v6::PROTOCOL,
+            data: value.data.into(),
+        }
+    }
+}
+
+impl From<v5::response::AuthenticatorResponseData> for v6::response::AuthenticatorResponseData {
+    fn from(authenticator_response_data: v5::response::AuthenticatorResponseData) -> Self {
+        match authenticator_response_data {
+            v5::response::AuthenticatorResponseData::PendingRegistration(pending_response) => {
+                v6::response::AuthenticatorResponseData::PendingRegistration(
+                    pending_response.into(),
+                )
+            }
+            v5::response::AuthenticatorResponseData::Registered(registered_response) => {
+                v6::response::AuthenticatorResponseData::Registered(registered_response.into())
+            }
+            v5::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response,
+            ) => v6::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response.into(),
+            ),
+            v5::response::AuthenticatorResponseData::TopUpBandwidth(top_up_response) => {
+                v6::response::AuthenticatorResponseData::TopUpBandwidth(top_up_response.into())
+            }
+        }
+    }
+}
+
+impl From<v5::response::RegisteredResponse> for v6::response::RegisteredResponse {
+    fn from(value: v5::response::RegisteredResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply: value.reply.into(),
+            upgrade_mode_enabled: false,
+        }
+    }
+}
+
+impl From<v5::response::PendingRegistrationResponse> for v6::response::PendingRegistrationResponse {
+    fn from(value: v5::response::PendingRegistrationResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply: value.reply.into(),
+            upgrade_mode_enabled: false,
+        }
+    }
+}
+
+impl From<v5::registration::RegistrationData> for v6::registration::RegistrationData {
+    fn from(value: v5::registration::RegistrationData) -> Self {
+        Self {
+            nonce: value.nonce,
+            gateway_data: value.gateway_data.into(),
+            wg_port: value.wg_port,
+        }
+    }
+}
+
+impl From<v6::registration::RegistrationData> for v5::registration::RegistrationData {
+    fn from(value: v6::registration::RegistrationData) -> Self {
+        Self {
+            nonce: value.nonce,
+            gateway_data: value.gateway_data.into(),
+            wg_port: value.wg_port,
+        }
+    }
+}
+
+impl From<v5::response::RemainingBandwidthResponse> for v6::response::RemainingBandwidthResponse {
+    fn from(value: v5::response::RemainingBandwidthResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply: value.reply.map(Into::into),
+            upgrade_mode_enabled: false,
+        }
+    }
+}
+
+impl From<v5::response::TopUpBandwidthResponse> for v6::response::TopUpBandwidthResponse {
+    fn from(value: v5::response::TopUpBandwidthResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply: value.reply.into(),
+            upgrade_mode_enabled: false,
+        }
+    }
+}
+
+impl From<v5::registration::RegisteredData> for v6::registration::RegisteredData {
+    fn from(value: v5::registration::RegisteredData) -> Self {
+        Self {
+            pub_key: value.pub_key,
+            private_ips: value.private_ips.into(),
+            wg_port: value.wg_port,
+        }
+    }
+}
+
+impl From<v5::registration::RemainingBandwidthData> for v6::registration::RemainingBandwidthData {
+    fn from(value: v5::registration::RemainingBandwidthData) -> Self {
+        Self {
+            available_bandwidth: value.available_bandwidth,
+        }
+    }
+}
+
+impl From<v5::registration::IpPair> for v6::registration::IpPair {
+    fn from(value: v5::registration::IpPair) -> Self {
+        Self {
+            ipv4: value.ipv4,
+            ipv6: value.ipv6,
+        }
+    }
+}
+
+impl From<v6::registration::IpPair> for v5::registration::IpPair {
+    fn from(value: v6::registration::IpPair) -> Self {
+        Self {
+            ipv4: value.ipv4,
+            ipv6: value.ipv6,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::{
+        net::{Ipv4Addr, Ipv6Addr},
+        str::FromStr,
+    };
+
+    use nym_credentials_interface::{BandwidthCredential, CredentialSpendingData, TicketType};
+    use nym_crypto::asymmetric::x25519::PrivateKey;
+    use nym_wireguard_types::PeerPublicKey;
+    use x25519_dalek::PublicKey;
+
+    use super::*;
+    use crate::models::BandwidthClaim;
+    use crate::{util::tests::CREDENTIAL_BYTES, v5};
+
+    #[test]
+    fn upgrade_initial_req() {
+        let pub_key = PeerPublicKey::new(PublicKey::from([0; 32]));
+
+        let (msg, _) = v5::request::AuthenticatorRequest::new_initial_request(
+            v5::registration::InitMessage::new(pub_key),
+        );
+        let upgraded_msg = v6::request::AuthenticatorRequest::try_from(msg).unwrap();
+
+        assert_eq!(upgraded_msg.protocol, v6::PROTOCOL);
+        assert_eq!(
+            upgraded_msg.data,
+            v6::request::AuthenticatorRequestData::Initial(v6::registration::InitMessage {
+                pub_key
+            })
+        );
+    }
+
+    #[test]
+    fn upgrade_final_req() {
+        let mut rng = rand::thread_rng();
+
+        let local_secret = PrivateKey::new(&mut rng);
+        let remote_secret = x25519_dalek::StaticSecret::random_from_rng(&mut rng);
+        let ipv4 = Ipv4Addr::from_str("10.10.10.10").unwrap();
+        let ipv6 = Ipv6Addr::from_str("fc01::a0a").unwrap();
+        let ips = v5::registration::IpPair::new(ipv4, ipv6);
+        let nonce = 42;
+        let gateway_client = v5::registration::GatewayClient::new(
+            &local_secret,
+            (&remote_secret).into(),
+            ips,
+            nonce,
+        );
+        let credential = CredentialSpendingData::try_from_bytes(&CREDENTIAL_BYTES).unwrap();
+        let final_message = v5::registration::FinalMessage {
+            gateway_client: gateway_client.clone(),
+            credential: Some(credential.clone()),
+        };
+
+        let (msg, _) = v5::request::AuthenticatorRequest::new_final_request(final_message);
+        let upgraded_msg = v6::request::AuthenticatorRequest::try_from(msg).unwrap();
+
+        assert_eq!(upgraded_msg.protocol, v6::PROTOCOL);
+        assert_eq!(
+            upgraded_msg.data,
+            v6::request::AuthenticatorRequestData::Final(Box::new(
+                v6::registration::FinalMessage {
+                    gateway_client: v6::registration::GatewayClient::new(
+                        &local_secret,
+                        (&remote_secret).into(),
+                        v6::registration::IpPair::new(ipv4, ipv6),
+                        nonce
+                    ),
+                    credential: Some(BandwidthClaim {
+                        credential: BandwidthCredential::ZkNym(Box::new(credential)),
+                        kind: TicketType::V1MixnetEntry,
+                    })
+                }
+            ))
+        );
+    }
+
+    #[test]
+    fn upgrade_query_req() {
+        let pub_key = PeerPublicKey::new(PublicKey::from([0; 32]));
+
+        let (msg, _) = v5::request::AuthenticatorRequest::new_query_request(pub_key);
+        let upgraded_msg = v6::request::AuthenticatorRequest::try_from(msg).unwrap();
+
+        assert_eq!(upgraded_msg.protocol, v6::PROTOCOL);
+        assert_eq!(
+            upgraded_msg.data,
+            v6::request::AuthenticatorRequestData::QueryBandwidth(pub_key)
+        );
+    }
+
+    #[test]
+    fn upgrade_pending_reg_resp() {
+        let mut rng = rand::thread_rng();
+
+        let local_secret = PrivateKey::new(&mut rng);
+        let remote_secret = x25519_dalek::StaticSecret::random_from_rng(&mut rng);
+        let ipv4 = Ipv4Addr::from_str("10.10.10.10").unwrap();
+        let ipv6 = Ipv6Addr::from_str("fc01::a0a").unwrap();
+        let ips = v5::registration::IpPair::new(ipv4, ipv6);
+        let nonce = 42;
+        let wg_port = 51822;
+        let gateway_data = v5::registration::GatewayClient::new(
+            &local_secret,
+            (&remote_secret).into(),
+            ips,
+            nonce,
+        );
+        let registration_data = v5::registration::RegistrationData {
+            nonce,
+            gateway_data,
+            wg_port,
+        };
+        let request_id = 123;
+
+        let msg = v5::response::AuthenticatorResponse::new_pending_registration_success(
+            registration_data,
+            request_id,
+        );
+        let upgraded_msg = v6::response::AuthenticatorResponse::from(msg);
+
+        assert_eq!(upgraded_msg.protocol, v6::PROTOCOL);
+
+        assert_eq!(
+            upgraded_msg.data,
+            v6::response::AuthenticatorResponseData::PendingRegistration(
+                v6::response::PendingRegistrationResponse {
+                    request_id,
+                    reply: v6::registration::RegistrationData {
+                        nonce,
+                        gateway_data: v6::registration::GatewayClient::new(
+                            &local_secret,
+                            (&remote_secret).into(),
+                            v6::registration::IpPair::new(ipv4, ipv6),
+                            nonce
+                        ),
+                        wg_port
+                    },
+                    upgrade_mode_enabled: false,
+                }
+            )
+        );
+    }
+
+    #[test]
+    fn upgrade_registered_resp() {
+        let pub_key = PeerPublicKey::new(PublicKey::from([0; 32]));
+        let ipv4 = Ipv4Addr::from_str("10.1.10.10").unwrap();
+        let ipv6 = Ipv6Addr::from_str("fc01::a0a").unwrap();
+        let private_ips = v5::registration::IpPair::new(ipv4, ipv6);
+        let wg_port = 51822;
+        let registered_data = v5::registration::RegisteredData {
+            pub_key,
+            private_ips,
+            wg_port,
+        };
+        let request_id = 123;
+
+        let msg = v5::response::AuthenticatorResponse::new_registered(registered_data, request_id);
+        let upgraded_msg = v6::response::AuthenticatorResponse::from(msg);
+
+        assert_eq!(upgraded_msg.protocol, v6::PROTOCOL);
+        assert_eq!(
+            upgraded_msg.data,
+            v6::response::AuthenticatorResponseData::Registered(v6::response::RegisteredResponse {
+                request_id,
+                reply: v6::registration::RegisteredData {
+                    wg_port,
+                    pub_key,
+                    private_ips: v6::registration::IpPair::new(ipv4, ipv6)
+                },
+                upgrade_mode_enabled: false,
+            })
+        );
+    }
+
+    #[test]
+    fn upgrade_remaining_bandwidth_resp() {
+        let available_bandwidth = 42;
+        let remaining_bandwidth_data = Some(v5::registration::RemainingBandwidthData {
+            available_bandwidth,
+        });
+        let request_id = 123;
+
+        let msg = v5::response::AuthenticatorResponse::new_remaining_bandwidth(
+            remaining_bandwidth_data,
+            request_id,
+        );
+        let upgraded_msg = v6::response::AuthenticatorResponse::from(msg);
+
+        assert_eq!(upgraded_msg.protocol, v6::PROTOCOL);
+        assert_eq!(
+            upgraded_msg.data,
+            v6::response::AuthenticatorResponseData::RemainingBandwidth(
+                v6::response::RemainingBandwidthResponse {
+                    request_id,
+                    reply: Some(v6::registration::RemainingBandwidthData {
+                        available_bandwidth,
+                    }),
+                    upgrade_mode_enabled: false,
+                }
+            )
+        );
+    }
+}
@@ -0,0 +1,15 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+
+pub mod conversion;
+pub mod registration;
+pub mod request;
+pub mod response;
+pub mod topup;
+pub mod upgrade_mode_check;
+
+pub const VERSION: u8 = 6;
+
+pub const PROTOCOL: Protocol = Protocol::new(VERSION, ServiceProviderType::Authenticator);
@@ -0,0 +1,287 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::error::Error;
+use crate::models::BandwidthClaim;
+use base64::{Engine, engine::general_purpose};
+use nym_network_defaults::constants::{WG_TUN_DEVICE_IP_ADDRESS_V4, WG_TUN_DEVICE_IP_ADDRESS_V6};
+use nym_wireguard_types::PeerPublicKey;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+use std::time::SystemTime;
+use std::{fmt, ops::Deref, str::FromStr};
+
+#[cfg(feature = "verify")]
+use hmac::{Hmac, Mac};
+#[cfg(feature = "verify")]
+use nym_crypto::asymmetric::x25519::{PrivateKey, PublicKey};
+#[cfg(feature = "verify")]
+use sha2::Sha256;
+
+pub type PendingRegistrations = HashMap<PeerPublicKey, RegistrationData>;
+pub type PrivateIPs = HashMap<IpPair, Taken>;
+
+#[cfg(feature = "verify")]
+pub type HmacSha256 = Hmac<Sha256>;
+
+pub type Nonce = u64;
+pub type Taken = Option<SystemTime>;
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub struct IpPair {
+    pub ipv4: Ipv4Addr,
+    pub ipv6: Ipv6Addr,
+}
+
+impl IpPair {
+    pub fn new(ipv4: Ipv4Addr, ipv6: Ipv6Addr) -> Self {
+        IpPair { ipv4, ipv6 }
+    }
+}
+
+impl From<(Ipv4Addr, Ipv6Addr)> for IpPair {
+    fn from((ipv4, ipv6): (Ipv4Addr, Ipv6Addr)) -> Self {
+        IpPair { ipv4, ipv6 }
+    }
+}
+
+impl fmt::Display for IpPair {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "({}, {})", self.ipv4, self.ipv6)
+    }
+}
+
+impl From<IpAddr> for IpPair {
+    fn from(value: IpAddr) -> Self {
+        let (before_last_byte, last_byte) = match value {
+            IpAddr::V4(ipv4_addr) => (ipv4_addr.octets()[2], ipv4_addr.octets()[3]),
+            IpAddr::V6(ipv6_addr) => (ipv6_addr.octets()[14], ipv6_addr.octets()[15]),
+        };
+        let last_bytes = ((before_last_byte as u16) << 8) | last_byte as u16;
+        let ipv4 = Ipv4Addr::new(
+            WG_TUN_DEVICE_IP_ADDRESS_V4.octets()[0],
+            WG_TUN_DEVICE_IP_ADDRESS_V4.octets()[1],
+            before_last_byte,
+            last_byte,
+        );
+        let ipv6 = Ipv6Addr::new(
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[0],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[1],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[2],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[3],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[4],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[5],
+            WG_TUN_DEVICE_IP_ADDRESS_V6.segments()[6],
+            last_bytes,
+        );
+        IpPair::new(ipv4, ipv6)
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct InitMessage {
+    /// Base64 encoded x25519 public key
+    pub pub_key: PeerPublicKey,
+}
+
+impl InitMessage {
+    pub fn new(pub_key: PeerPublicKey) -> Self {
+        InitMessage { pub_key }
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct FinalMessage {
+    /// Gateway client data
+    pub gateway_client: GatewayClient,
+
+    /// Ecash credential
+    pub credential: Option<BandwidthClaim>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct RegistrationData {
+    pub nonce: u64,
+    pub gateway_data: GatewayClient,
+    pub wg_port: u16,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct RegisteredData {
+    pub pub_key: PeerPublicKey,
+    pub private_ips: IpPair,
+    pub wg_port: u16,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct RemainingBandwidthData {
+    pub available_bandwidth: i64,
+}
+
+/// Client that wants to register sends its PublicKey bytes mac digest encrypted with a DH shared secret.
+/// Gateway/Nym node can then verify pub_key payload using the same process
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct GatewayClient {
+    /// Base64 encoded x25519 public key
+    pub pub_key: PeerPublicKey,
+
+    /// Assigned private IPs (v4 and v6)
+    pub private_ips: IpPair,
+
+    /// Sha256 hmac on the data (alongside the prior nonce)
+    pub mac: ClientMac,
+}
+
+impl GatewayClient {
+    #[cfg(feature = "verify")]
+    pub fn new(
+        local_secret: &PrivateKey,
+        remote_public: x25519_dalek::PublicKey,
+        private_ips: IpPair,
+        nonce: u64,
+    ) -> Self {
+        let local_public = PublicKey::from(local_secret);
+        let remote_public = PublicKey::from(remote_public);
+
+        let dh = local_secret.diffie_hellman(&remote_public);
+
+        // TODO: change that to use our nym_crypto::hmac module instead
+        #[allow(clippy::expect_used)]
+        let mut mac = HmacSha256::new_from_slice(&dh[..])
+            .expect("x25519 shared secret is always 32 bytes long");
+
+        mac.update(local_public.as_bytes());
+        mac.update(private_ips.to_string().as_bytes());
+        mac.update(&nonce.to_le_bytes());
+
+        GatewayClient {
+            pub_key: PeerPublicKey::new(local_public.into()),
+            private_ips,
+            mac: ClientMac(mac.finalize().into_bytes().to_vec()),
+        }
+    }
+
+    // Reusable secret should be gateways Wireguard PK
+    // Client should perform this step when generating its payload, using its own WG PK
+    #[cfg(feature = "verify")]
+    pub fn verify(&self, gateway_key: &PrivateKey, nonce: u64) -> Result<(), Error> {
+        // use gateways key as a ref to an x25519_dalek key
+        let dh = gateway_key.inner().diffie_hellman(&self.pub_key);
+
+        // TODO: change that to use our nym_crypto::hmac module instead
+        #[allow(clippy::expect_used)]
+        let mut mac = HmacSha256::new_from_slice(dh.as_bytes())
+            .expect("x25519 shared secret is always 32 bytes long");
+
+        mac.update(self.pub_key.as_bytes());
+        mac.update(self.private_ips.to_string().as_bytes());
+        mac.update(&nonce.to_le_bytes());
+
+        mac.verify_slice(&self.mac)
+            .map_err(|source| Error::FailedClientMacVerification {
+                client: self.pub_key.to_string(),
+                source,
+            })
+    }
+
+    pub fn pub_key(&self) -> PeerPublicKey {
+        self.pub_key
+    }
+}
+
+// TODO: change the inner type into generic array of size HmacSha256::OutputSize
+// TODO2: rely on our internal crypto/hmac
+#[derive(Debug, Clone, PartialEq)]
+pub struct ClientMac(Vec<u8>);
+
+impl fmt::Display for ClientMac {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", general_purpose::STANDARD.encode(&self.0))
+    }
+}
+
+impl From<Vec<u8>> for ClientMac {
+    fn from(v: Vec<u8>) -> Self {
+        ClientMac(v)
+    }
+}
+
+impl ClientMac {
+    #[allow(dead_code)]
+    pub fn new(mac: Vec<u8>) -> Self {
+        ClientMac(mac)
+    }
+}
+
+impl Deref for ClientMac {
+    type Target = Vec<u8>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl FromStr for ClientMac {
+    type Err = Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let mac_bytes: Vec<u8> =
+            general_purpose::STANDARD
+                .decode(s)
+                .map_err(|source| Error::MalformedClientMac {
+                    mac: s.to_string(),
+                    source,
+                })?;
+
+        Ok(ClientMac(mac_bytes))
+    }
+}
+
+impl Serialize for ClientMac {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        let encoded_key = general_purpose::STANDARD.encode(self.0.clone());
+        serializer.serialize_str(&encoded_key)
+    }
+}
+
+impl<'de> Deserialize<'de> for ClientMac {
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let encoded_key = String::deserialize(deserializer)?;
+        ClientMac::from_str(&encoded_key).map_err(serde::de::Error::custom)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use nym_crypto::asymmetric::x25519;
+    use nym_test_utils::helpers::deterministic_rng;
+
+    #[test]
+    fn create_ip_pair() {
+        let ipv4: IpAddr = Ipv4Addr::from_str("10.1.10.50").unwrap().into();
+        let ipv6: IpAddr = Ipv6Addr::from_str("fc01::0a32").unwrap().into();
+
+        assert_eq!(IpPair::from(ipv4), IpPair::from(ipv6));
+    }
+
+    #[test]
+    #[cfg(feature = "verify")]
+    fn client_request_roundtrip() {
+        let mut rng = deterministic_rng();
+
+        let gateway_key_pair = x25519::KeyPair::new(&mut rng);
+        let client_key_pair = x25519::KeyPair::new(&mut rng);
+
+        let nonce = 1234567890;
+
+        let client = GatewayClient::new(
+            client_key_pair.private_key(),
+            x25519_dalek::PublicKey::from(gateway_key_pair.public_key().to_bytes()),
+            IpPair::new("10.0.0.42".parse().unwrap(), "fc00::42".parse().unwrap()),
+            nonce,
+        );
+        assert!(client.verify(gateway_key_pair.private_key(), nonce).is_ok())
+    }
+}
@@ -0,0 +1,135 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::{
+    PROTOCOL,
+    registration::{FinalMessage, InitMessage},
+    topup::TopUpMessage,
+    upgrade_mode_check::UpgradeModeCheckRequest,
+};
+use nym_service_provider_requests_common::Protocol;
+use nym_wireguard_types::PeerPublicKey;
+use serde::{Deserialize, Serialize};
+
+use crate::make_bincode_serializer;
+
+fn generate_random() -> u64 {
+    use rand::RngCore;
+    let mut rng = rand::rngs::OsRng;
+    rng.next_u64()
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct AuthenticatorRequest {
+    pub protocol: Protocol,
+    pub data: AuthenticatorRequestData,
+    pub request_id: u64,
+}
+
+impl AuthenticatorRequest {
+    pub fn from_reconstructed_message(
+        message: &nym_sphinx::receiver::ReconstructedMessage,
+    ) -> Result<Self, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().deserialize(&message.message)
+    }
+
+    pub fn new_initial_request(init_message: InitMessage) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: PROTOCOL,
+                data: AuthenticatorRequestData::Initial(init_message),
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn new_final_request(final_message: FinalMessage) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: PROTOCOL,
+                data: AuthenticatorRequestData::Final(Box::new(final_message)),
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn new_query_request(peer_public_key: PeerPublicKey) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: PROTOCOL,
+                data: AuthenticatorRequestData::QueryBandwidth(peer_public_key),
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn new_topup_request(top_up_message: TopUpMessage) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: PROTOCOL,
+                data: AuthenticatorRequestData::TopUpBandwidth(Box::new(top_up_message)),
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn new_upgrade_mode_check_request(message: UpgradeModeCheckRequest) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: PROTOCOL,
+                data: AuthenticatorRequestData::CheckUpgradeMode(message),
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().serialize(self)
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub enum AuthenticatorRequestData {
+    Initial(InitMessage),
+    Final(Box<FinalMessage>),
+    QueryBandwidth(PeerPublicKey),
+    TopUpBandwidth(Box<TopUpMessage>),
+    CheckUpgradeMode(UpgradeModeCheckRequest),
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::VERSION;
+    use super::*;
+    use nym_service_provider_requests_common::ServiceProviderType;
+    use std::str::FromStr;
+
+    #[test]
+    fn check_first_bytes_protocol() {
+        let version = VERSION;
+        let data = AuthenticatorRequest {
+            protocol: Protocol {
+                version,
+                service_provider_type: ServiceProviderType::Authenticator,
+            },
+            data: AuthenticatorRequestData::Initial(InitMessage::new(
+                PeerPublicKey::from_str("yvNUDpT5l7W/xDhiu6HkqTHDQwbs/B3J5UrLmORl1EQ=").unwrap(),
+            )),
+            request_id: 1,
+        };
+        let bytes = *data.to_bytes().unwrap().first_chunk::<2>().unwrap();
+        assert_eq!(bytes, [version, ServiceProviderType::Authenticator as u8]);
+    }
+}
@@ -0,0 +1,153 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::registration::{RegisteredData, RegistrationData, RemainingBandwidthData};
+use nym_service_provider_requests_common::Protocol;
+use serde::{Deserialize, Serialize};
+
+use crate::make_bincode_serializer;
+
+use super::PROTOCOL;
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct AuthenticatorResponse {
+    pub protocol: Protocol,
+    pub data: AuthenticatorResponseData,
+}
+
+impl AuthenticatorResponse {
+    pub fn new_pending_registration_success(
+        registration_data: RegistrationData,
+        request_id: u64,
+        upgrade_mode_enabled: bool,
+    ) -> Self {
+        Self {
+            protocol: PROTOCOL,
+            data: AuthenticatorResponseData::PendingRegistration(PendingRegistrationResponse {
+                reply: registration_data,
+                request_id,
+                upgrade_mode_enabled,
+            }),
+        }
+    }
+
+    pub fn new_registered(
+        registered_data: RegisteredData,
+        request_id: u64,
+        upgrade_mode_enabled: bool,
+    ) -> Self {
+        Self {
+            protocol: PROTOCOL,
+            data: AuthenticatorResponseData::Registered(RegisteredResponse {
+                reply: registered_data,
+                request_id,
+                upgrade_mode_enabled,
+            }),
+        }
+    }
+
+    pub fn new_remaining_bandwidth(
+        remaining_bandwidth_data: Option<RemainingBandwidthData>,
+        request_id: u64,
+        upgrade_mode_enabled: bool,
+    ) -> Self {
+        Self {
+            protocol: PROTOCOL,
+            data: AuthenticatorResponseData::RemainingBandwidth(RemainingBandwidthResponse {
+                reply: remaining_bandwidth_data,
+                request_id,
+                upgrade_mode_enabled,
+            }),
+        }
+    }
+
+    pub fn new_topup_bandwidth(
+        remaining_bandwidth_data: RemainingBandwidthData,
+        request_id: u64,
+        upgrade_mode_enabled: bool,
+    ) -> Self {
+        Self {
+            protocol: PROTOCOL,
+            data: AuthenticatorResponseData::TopUpBandwidth(TopUpBandwidthResponse {
+                reply: remaining_bandwidth_data,
+                request_id,
+                upgrade_mode_enabled,
+            }),
+        }
+    }
+
+    pub fn new_upgrade_mode_check(request_id: u64, upgrade_mode_enabled: bool) -> Self {
+        Self {
+            protocol: PROTOCOL,
+            data: AuthenticatorResponseData::UpgradeMode(UpgradeModeResponse {
+                request_id,
+                upgrade_mode_enabled,
+            }),
+        }
+    }
+
+    pub fn to_bytes(&self) -> Result<Vec<u8>, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().serialize(self)
+    }
+
+    pub fn from_reconstructed_message(
+        message: &nym_sphinx::receiver::ReconstructedMessage,
+    ) -> Result<Self, bincode::Error> {
+        use bincode::Options;
+        make_bincode_serializer().deserialize(&message.message)
+    }
+
+    pub fn id(&self) -> Option<u64> {
+        match &self.data {
+            AuthenticatorResponseData::PendingRegistration(response) => Some(response.request_id),
+            AuthenticatorResponseData::Registered(response) => Some(response.request_id),
+            AuthenticatorResponseData::RemainingBandwidth(response) => Some(response.request_id),
+            AuthenticatorResponseData::TopUpBandwidth(response) => Some(response.request_id),
+            AuthenticatorResponseData::UpgradeMode(response) => Some(response.request_id),
+        }
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub enum AuthenticatorResponseData {
+    PendingRegistration(PendingRegistrationResponse),
+    Registered(RegisteredResponse),
+    RemainingBandwidth(RemainingBandwidthResponse),
+    TopUpBandwidth(TopUpBandwidthResponse),
+    UpgradeMode(UpgradeModeResponse),
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct PendingRegistrationResponse {
+    pub request_id: u64,
+    pub reply: RegistrationData,
+    pub upgrade_mode_enabled: bool,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct RegisteredResponse {
+    pub request_id: u64,
+    pub reply: RegisteredData,
+    pub upgrade_mode_enabled: bool,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct RemainingBandwidthResponse {
+    pub request_id: u64,
+    pub reply: Option<RemainingBandwidthData>,
+    pub upgrade_mode_enabled: bool,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct TopUpBandwidthResponse {
+    pub request_id: u64,
+    pub reply: RemainingBandwidthData,
+    pub upgrade_mode_enabled: bool,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct UpgradeModeResponse {
+    pub request_id: u64,
+    pub upgrade_mode_enabled: bool,
+}
@@ -0,0 +1,15 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_credentials_interface::CredentialSpendingData;
+use nym_wireguard_types::PeerPublicKey;
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct TopUpMessage {
+    /// Base64 encoded x25519 public key
+    pub pub_key: PeerPublicKey,
+
+    /// Ecash credential
+    pub credential: CredentialSpendingData,
+}
@@ -0,0 +1,12 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+#[non_exhaustive]
+pub enum UpgradeModeCheckRequest {
+    /// Attempt to request upgrade mode recheck via the JWT issued as the result of
+    /// global attestation.json being published
+    UpgradeModeJwt { token: String },
+}
@@ -0,0 +1,211 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::{v1, v2, v3, v4, v5, v6};
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+
+#[derive(Copy, Clone, Debug, PartialEq, strum_macros::Display)]
+#[strum(serialize_all = "snake_case")]
+pub enum AuthenticatorVersion {
+    /// introduced in wispa release (1.1.5)
+    V1,
+
+    /// introduced in aero release (1.1.9)
+    V2,
+
+    /// introduced in magura release (1.1.10)
+    V3,
+
+    /// introduced in crunch release (1.2.0)
+    V4,
+
+    /// introduced in dorina-patched release (1.6.1)
+    V5,
+
+    /// introduced in niolo release (1.23.0)
+    V6,
+
+    /// an unknown, future, variant that can be present if running outdated software
+    UNKNOWN,
+}
+
+impl AuthenticatorVersion {
+    pub const LATEST: Self = Self::V6;
+
+    pub const fn release_version(&self) -> semver::Version {
+        match self {
+            AuthenticatorVersion::V1 => semver::Version::new(1, 1, 5),
+            AuthenticatorVersion::V2 => semver::Version::new(1, 1, 9),
+            AuthenticatorVersion::V3 => semver::Version::new(1, 1, 10),
+            AuthenticatorVersion::V4 => semver::Version::new(1, 2, 0),
+            AuthenticatorVersion::V5 => semver::Version::new(1, 6, 1),
+            AuthenticatorVersion::V6 => semver::Version::new(1, 23, 0),
+            AuthenticatorVersion::UNKNOWN => semver::Version::new(0, 0, 0),
+        }
+    }
+}
+
+impl From<Protocol> for AuthenticatorVersion {
+    fn from(value: Protocol) -> Self {
+        if value.service_provider_type != ServiceProviderType::Authenticator {
+            AuthenticatorVersion::UNKNOWN
+        } else if value.version == v1::VERSION {
+            AuthenticatorVersion::V1
+        } else if value.version == v2::VERSION {
+            AuthenticatorVersion::V2
+        } else if value.version == v3::VERSION {
+            AuthenticatorVersion::V3
+        } else if value.version == v4::VERSION {
+            AuthenticatorVersion::V4
+        } else if value.version == v5::VERSION {
+            AuthenticatorVersion::V5
+        } else if value.version == v6::VERSION {
+            AuthenticatorVersion::V6
+        } else {
+            AuthenticatorVersion::UNKNOWN
+        }
+    }
+}
+
+impl From<u8> for AuthenticatorVersion {
+    fn from(value: u8) -> Self {
+        if value == v1::VERSION {
+            AuthenticatorVersion::V1
+        } else if value == v2::VERSION {
+            AuthenticatorVersion::V2
+        } else if value == v3::VERSION {
+            AuthenticatorVersion::V3
+        } else if value == v4::VERSION {
+            AuthenticatorVersion::V4
+        } else if value == v5::VERSION {
+            AuthenticatorVersion::V5
+        } else if value == v6::VERSION {
+            AuthenticatorVersion::V6
+        } else {
+            AuthenticatorVersion::UNKNOWN
+        }
+    }
+}
+
+impl From<&str> for AuthenticatorVersion {
+    fn from(value: &str) -> Self {
+        let Ok(semver) = semver::Version::parse(value) else {
+            return Self::UNKNOWN;
+        };
+
+        semver.into()
+    }
+}
+
+impl From<Option<&String>> for AuthenticatorVersion {
+    fn from(value: Option<&String>) -> Self {
+        match value {
+            None => Self::UNKNOWN,
+            Some(value) => value.as_str().into(),
+        }
+    }
+}
+
+impl From<String> for AuthenticatorVersion {
+    fn from(value: String) -> Self {
+        Self::from(value.as_str())
+    }
+}
+
+impl From<Option<String>> for AuthenticatorVersion {
+    fn from(value: Option<String>) -> Self {
+        value.as_ref().into()
+    }
+}
+
+impl From<semver::Version> for AuthenticatorVersion {
+    fn from(semver: semver::Version) -> Self {
+        if semver < AuthenticatorVersion::V1.release_version() {
+            return Self::UNKNOWN;
+        }
+        if semver < AuthenticatorVersion::V2.release_version() {
+            return Self::V1;
+        }
+        if semver < AuthenticatorVersion::V3.release_version() {
+            return Self::V2;
+        }
+        if semver < AuthenticatorVersion::V4.release_version() {
+            return Self::V3;
+        }
+        if semver < AuthenticatorVersion::V5.release_version() {
+            return Self::V4;
+        }
+        if semver < AuthenticatorVersion::V6.release_version() {
+            return Self::V5;
+        }
+        // if provided version is higher (or equal) to release version of V6,
+        // we return the latest (i.e. v6)
+
+        debug_assert_eq!(
+            Self::V6,
+            Self::LATEST,
+            "a new AuthenticatorVersion variant has been introduced without adjusting the `From<semver::Version>` trait"
+        );
+        Self::LATEST
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::latest;
+    use super::*;
+
+    #[test]
+    fn strum_display() {
+        // sanity check on formatting and casing
+        assert_eq!("v1", AuthenticatorVersion::V1.to_string());
+        assert_eq!("v2", AuthenticatorVersion::V2.to_string());
+        assert_eq!("unknown", AuthenticatorVersion::UNKNOWN.to_string());
+    }
+
+    #[test]
+    fn u8_conversion() {
+        assert_eq!(AuthenticatorVersion::V1, AuthenticatorVersion::from(1u8));
+        assert_eq!(AuthenticatorVersion::V2, AuthenticatorVersion::from(2u8));
+
+        assert_eq!(
+            AuthenticatorVersion::UNKNOWN,
+            AuthenticatorVersion::from(latest::VERSION + 1)
+        );
+        assert_eq!(
+            AuthenticatorVersion::UNKNOWN,
+            AuthenticatorVersion::from(0u8)
+        );
+        assert_eq!(
+            AuthenticatorVersion::UNKNOWN,
+            AuthenticatorVersion::from(255u8)
+        );
+    }
+
+    #[test]
+    fn semver_checks() {
+        assert_eq!(AuthenticatorVersion::UNKNOWN, "1.1.4".into());
+        assert_eq!(AuthenticatorVersion::UNKNOWN, "0.1.0".into());
+        assert_eq!(AuthenticatorVersion::UNKNOWN, "1.0.4".into());
+        assert_eq!(AuthenticatorVersion::V1, "1.1.5".into());
+        assert_eq!(AuthenticatorVersion::V1, "1.1.6".into());
+        assert_eq!(AuthenticatorVersion::V1, "1.1.8".into());
+        assert_eq!(AuthenticatorVersion::V2, "1.1.9".into());
+        assert_eq!(AuthenticatorVersion::V3, "1.1.10".into());
+        assert_eq!(AuthenticatorVersion::V3, "1.1.11".into());
+        assert_eq!(AuthenticatorVersion::V3, "1.1.60".into());
+        assert_eq!(AuthenticatorVersion::V4, "1.2.0".into());
+        assert_eq!(AuthenticatorVersion::V4, "1.2.1".into());
+        assert_eq!(AuthenticatorVersion::V4, "1.5.1".into());
+        assert_eq!(AuthenticatorVersion::V4, "1.6.0".into());
+        assert_eq!(AuthenticatorVersion::V5, "1.6.1".into());
+        assert_eq!(AuthenticatorVersion::V5, "1.6.11".into());
+        assert_eq!(AuthenticatorVersion::V5, "1.7.0".into());
+        assert_eq!(AuthenticatorVersion::V5, "1.16.11".into());
+        assert_eq!(AuthenticatorVersion::V5, "1.17.0".into());
+        assert_eq!(AuthenticatorVersion::V5, "1.22.0".into());
+        assert_eq!(AuthenticatorVersion::V6, "1.23.0".into());
+        assert_eq!(AuthenticatorVersion::V6, "1.23.1".into());
+        assert_eq!(AuthenticatorVersion::V6, "1.24.0".into());
+    }
+}
@@ -7,20 +7,16 @@ license.workspace = true
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

 [dependencies]
-bip39 = { workspace = true }
+async-trait = { workspace = true }
 log = { workspace = true }
 rand = { workspace = true }
 thiserror = { workspace = true }
-url = { workspace = true }
-zeroize = { workspace = true }

 nym-credential-storage = { path = "../credential-storage" }
 nym-credentials = { path = "../credentials" }
 nym-credentials-interface = { path = "../credentials-interface" }
 nym-crypto = { path = "../crypto", features = ["rand", "asymmetric", "stream_cipher", "aes", "hashing"] }
-nym-ecash-contract-common = { path = "../cosmwasm-smart-contracts/ecash-contract" }
 nym-ecash-time = { path = "../ecash-time" }
-nym-network-defaults = { path = "../network-defaults" }
 nym-task = { path = "../task" }
 nym-validator-client = { path = "../client-libs/validator-client", default-features = false }

@@ -21,6 +21,9 @@ pub enum BandwidthControllerError {
    #[error("There was a credential storage error - {0}")]
    CredentialStorageError(Box<dyn std::error::Error + Send + Sync>),

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

@@ -12,7 +12,7 @@ use crate::utils::{
    ApiClientsWrapper,
 };
 use log::error;
-use nym_credential_storage::models::RetrievedTicketbook;
+use nym_credential_storage::models::{EmergencyCredential, RetrievedTicketbook};
 use nym_credential_storage::storage::Storage;
 use nym_credentials::ecash::bandwidth::CredentialSpendingData;
 use nym_credentials_interface::{
@@ -23,10 +23,12 @@ use nym_validator_client::nym_api::EpochId;
 use nym_validator_client::nyxd::contract_traits::DkgQueryClient;

 pub use event::BandwidthStatusMessage;
+pub use traits::{BandwidthTicketProvider, DEFAULT_TICKETS_TO_SPEND};

 pub mod acquire;
 pub mod error;
 mod event;
+mod traits;
 mod utils;

 #[derive(Debug)]
@@ -218,6 +220,19 @@ impl<C, St: Storage> BandwidthController<C, St> {
            }
        }
    }
+
+    pub async fn get_emergency_credential(
+        &self,
+        typ: &str,
+    ) -> Result<Option<EmergencyCredential>, BandwidthControllerError>
+    where
+        <St as Storage>::StorageError: Send + Sync + 'static,
+    {
+        self.storage
+            .get_emergency_credential(typ)
+            .await
+            .map_err(BandwidthControllerError::credential_storage_error)
+    }
 }

 impl<C, St> Clone for BandwidthController<C, St>
--- a/Show More
+++ b/Show More