Various fixes

KKT + PSQ (#6203 )
* Add nymkkt with KKT convenience wrappers for nym-lp integration Integrates nymkkt module from georgio/noise-psq branch to enable post-quantum key distribution for nym-lp. Changes: - Add common/nymkkt from georgio/noise-psq (KKT protocol implementation) - Add convenience wrapper layer (kkt.rs) with simplified API: - request_kem_key() - Client requests gateway's KEM key - validate_kem_response() - Client validates signed response - handle_kem_request() - Gateway handles requests - Add nymkkt to workspace members in root Cargo.toml - Export kkt module in lib.rs The KKT (Key Encapsulation Mechanism Transport) protocol enables efficient distribution of post-quantum KEM public keys. Instead of storing large PQ keys in the directory (1KB-500KB), we store 32-byte hashes and fetch actual keys on-demand via this authenticated protocol. Tests: All 5 unit tests passing (authenticated, anonymous, signature verification, hash validation) * feat(lp): add Ed25519 authentication to PSQ protocol Replace basic PSQ v0 API with authenticated v1 API that includes cryptographic authentication via Ed25519 signatures. Changes: - PSQ initiator now signs encapsulated keys with Ed25519 private key - PSQ responder verifies Ed25519 signatures before deriving PSK - Prevents MITM attacks through mutual authentication - Fixed test helpers to use role-based Ed25519 keypair assignment (initiator uses [1u8;32], responder uses [2u8;32]) Security: This adds a critical authentication layer to the post-quantum PSK derivation protocol, ensuring both parties can verify each other's identity during the handshake. Tests: All 77 tests passing (was 11 failures, now 0) * feat(lp): integrate PSQ post-quantum PSK derivation Complete integration of Post-Quantum Secure (PSQ) protocol for PSK derivation in the Lewes Protocol, replacing simple Blake3 derivation with cryptographically secure DHKEM-based PSK establishment. This commit encompasses three completed tasks: - Add KKTRequest/KKTResponse message types to LpMessage enum - Update codec to handle KKT message serialization/deserialization - Add kkt_orchestrator.rs with high-level KKT API wrappers - Enable key exchange orchestration for PSQ protocol - Add set_psk() method to NoiseProtocol for dynamic PSK injection - Integrate PSQ derivation into LpSession handshake flow - PSQ payload embedded in first Noise message (ClientHello) - Derive PSK using libcrux-psq before Noise handshake completion - Add helper functions for X25519 to KEM conversions - Add comprehensive PSQ integration tests in session_integration/ - Test PSQ handshake end-to-end flow - Validate PSK derivation correctness between initiator/responder - Test PSQ + Noise combined protocol operation Dependencies: - libcrux-psq: Post-quantum PSK protocol implementation - libcrux-kem: Key Encapsulation Mechanism primitives - nym-kkt: KKT key exchange protocol wrappers - rand 0.9: Required for KKT compatibility Security: This adds Harvest-Now-Decrypt-Later (HNDL) resistance by combining classical ECDH with post-quantum KEM for PSK derivation. Even if X25519 is broken by quantum computers, the PSK remains secure. Tests: All 77 tests passing * feat(lp): add PSQ error handling documentation and tests (nym-bbi) Formalize the "always abort" error handling strategy for PSQ failures. PSQ errors indicate attacks, misconfigurations, or protocol violations that should not be silently ignored or worked around. Changes: - Add comprehensive error handling documentation to psk.rs module - Add diagnostic logging with error categorization: * CredError → warn about potential attack * TimestampElapsed → warn about potential replay * Other errors → log as errors - Add 4 error scenario tests: * test_psq_deserialization_failure * test_handshake_abort_on_psq_failure * test_psq_invalid_signature * test_psq_state_unchanged_on_error - Add log dependency to Cargo.toml Error handling strategy: All PSQ failures abort the handshake cleanly with no retry or fallback. This prevents silent security degradation and ensures misconfigurations are detected early. State guarantees: PSQ errors leave session in clean state - dummy PSK remains, Noise HandshakeState unchanged, no partial data, no cleanup needed. Tests: 81 tests passing (77 original + 4 new error tests) Closes: nym-bbi * feat(lp): add PSK injection tracking to prevent dummy PSK usage (nym-ep2) Add safety mechanism to ensure real post-quantum PSK was injected before allowing transport mode operations (encrypt/decrypt). This prevents accidentally using the insecure dummy PSK [0u8; 32] if PSQ injection fails. Changes: - Add `psk_injected: AtomicBool` field to LpSession - Initialize to `false` in LpSession::new() - Set to `true` after successful PSK injection: * Initiator: In prepare_handshake_message() after set_psk() * Responder: In process_handshake_message() after set_psk() - Add NoiseError::PskNotInjected error variant - Add PSK injection checks in encrypt_data() and decrypt_data() * Check happens before handshake completion check * Returns PskNotInjected if flag is false - Add comprehensive PSK injection lifecycle documentation to LpSession - Add test_transport_fails_without_psk_injection test - Update test_encrypt_decrypt_before_handshake to expect PskNotInjected PSK Injection Lifecycle: 1. Session created with dummy PSK [0u8; 32] in Noise HandshakeState 2. During handshake, PSQ runs and derives real post-quantum PSK 3. Real PSK injected via set_psk() - psk_injected flag set to true 4. Handshake completes, transport mode available 5. Transport operations check psk_injected flag for safety This is defensive programming - normal PSQ flow always injects the real PSK. The safety check prevents transport mode if PSQ somehow fails silently or is bypassed due to implementation bugs. Tests: 82 tests passing (81 original + 1 new) Closes: nym-ep2 * docs(lp): fix PSK state documentation inaccuracy Correct error handling documentation to clarify that PSK slot 3 remains unmodified only on error, not in all cases. Previous: "PSK slot 3 = dummy [0u8; 32] (never modified)" Corrected: "PSK slot 3 = dummy [0u8; 32] (not modified on error)" This is more accurate since: - On error: PSK remains as dummy value (never injected) - On success: PSK is replaced with real post-quantum PSK Documentation-only change, no functional impact. * feat(lp): add KKTExchange state to state machine for pre-handshake KEM key transfer (nym-4za) Add KKTExchange state to LpStateMachine to properly orchestrate KKT (KEM Key Transfer) protocol before Noise handshake begins. This enables dynamic KEM public key exchange, allowing post-quantum KEM algorithms to be used without pre-published keys. Changes: - Add KKTExchange state and KKTComplete action to state machine - Implement automatic KKT exchange on StartHandshake: * Initiator: sends KKT request → waits for response → validates signature * Responder: waits for request → validates → sends signed KEM key - Update process_kkt_response() to accept Option<&[u8]> for hash validation: * Some(hash): full KKT validation with directory hash (future) * None: signature-only mode (current deployment) - Add local_x25519_public() helper for responder KEM key derivation - Update state flow: ReadyToHandshake → KKTExchange → Handshaking → Transport - Add PSK handle storage (psk_handle) for future re-registration - Export generate_fresh_salt() for session creation - Update psq_responder_process_message() to return encrypted PSK handle (ctxt_B) - Add comprehensive tests: * test_kkt_exchange_initiator_flow * test_kkt_exchange_responder_flow * test_kkt_exchange_full_roundtrip * test_kkt_exchange_close * test_kkt_exchange_rejects_invalid_inputs * Updated test_state_machine_simplified_flow for KKT phase All tests passing. Ready for nym-8y5 (PSQ handshake KKT integration). * docs(lp): add state machine and post-quantum security protocol documentation Add comprehensive documentation of the Lewes Protocol state machine and post-quantum security architecture to LP_PROTOCOL.md. New sections: - State Machine and Security Protocol overview - Detailed state transition diagram (ReadyToHandshake → KKTExchange → Handshaking → Transport) - Complete message sequence diagram showing KKT + PSQ + Noise flow - KKT (KEM Key Transfer) protocol specification - PSQ (Post-Quantum Secure PSK) protocol details - Security guarantees and implementation status - Algorithm choices (current X25519, future ML-KEM-768) - Message type specifications for KKT - Version 1.1 changelog entry documenting KKT/PSQ integration Documentation includes: - ASCII art state machine diagram - Message sequence diagram with all protocol phases - PSK derivation formulas - Security properties checklist - Migration path to post-quantum KEMs - Integration details (PSQ embedded in Noise, no extra round-trips) Related to nym-4za (KKTExchange state implementation). * feat(lp): use KKT-authenticated KEM key in PSQ handshake (nym-8y5) Replace direct X25519→KEM conversion with KKT-derived authenticated key in PSQ initiator flow. This ensures PSQ uses the responder's authenticated KEM public key obtained via KKT protocol instead of blindly converting their X25519 key, properly completing the post-quantum security chain. Changes: - session.rs: Extract KEM key from KKTState::Completed in prepare_handshake_message() - session.rs: Add set_kkt_completed_for_test() helper for test initialization - session.rs: Update create_handshake_test_session() to initialize KKT state - session.rs: Fix test_handshake_abort_on_psq_failure and test_psq_invalid_signature - session_manager.rs: Add init_kkt_for_test() for integration test setup - session_integration/mod.rs: Update tests for KKT-first flow (6 rounds total) - session_integration/mod.rs: Fix state machine test expectations for KKTExchange state All 87 tests passing. Unblocks nym-w8f (KKT tests) and nym-m15 (production integration). * feat(lp): simplify API to Ed25519-only, derive X25519 internally Refactored LP state machine to use Ed25519 keys exclusively in the public API, with X25519 keys derived internally via RFC 7748. This simplifies the API from 6 parameters to 4 while maintaining protocol security. **Core API Changes:** - LpStateMachine::new(): Removed explicit X25519 keypair parameters - Old: new(is_initiator, local_keypair, local_ed25519_keypair, remote_public_key, remote_ed25519_key, salt) - New: new(is_initiator, local_ed25519_keypair, remote_ed25519_key, salt) - X25519 keys now derived internally from Ed25519 using RFC 7748 - lp_id calculation moved inside state machine (uses derived X25519 keys) **Protocol Changes:** - ClientHello message extended from 65 to 97 bytes - Now includes client_ed25519_public_key field (32 bytes) - Required for PSQ authentication in KKT + PSQ handshake flow - Breaking change: gateway must extract Ed25519 from ClientHello **Gateway Updates:** - receive_client_hello() now extracts Ed25519 public key - LpGatewayHandshake::new_responder() accepts Ed25519 keys only - Removed manual X25519 conversion (handled by state machine) **Registration Client Updates:** - LpRegistrationClient now uses Ed25519 keypairs - Generate fresh ephemeral Ed25519 keys for LP registration - ClientHello includes Ed25519 public key for gateway authentication - Fixed 7 pre-existing build errors: * mixnet_client_startup_timeout field removal * IprClientConnect API change (async → sync) * Error variant renames (use helper function) * LP client key type mismatches (X25519 → Ed25519) **Test Suite:** - Updated 16+ test functions to use new 4-parameter constructor - Fixed 5 integration test failures caused by lp_id mismatch - Tests now derive X25519 from Ed25519 (matching production behavior) - Added missing PublicKey imports in test modules - All 87 tests passing (100% success rate) **Implementation Details:** - Added Ed25519RecoveryError variant to LpError enum - Type conversion: nym_crypto X25519 → nym_lp keypair types - Maintained backward compatibility for PSQ/KKT protocol flow - Session manager updated to use new API signature This change completes the Ed25519-only API migration, hiding X25519 as an implementation detail while preserving all security properties of the KKT-authenticated PSQ handshake protocol. * chore: run cargo fmt * chore: run cargo clippy --fix to resolve simple linter issues * Basic handshake working * Final tweaks * Wrap PR comments, 2024 --------- Co-authored-by: Jędrzej Stuczyński <jedrzej.stuczynski@gmail.com>
2025-11-24 12:13:17 +01:00 · 2025-11-21 18:37:38 +01:00 · 2025-11-21 18:25:47 +01:00 · 2025-11-21 18:25:47 +01:00 · 2025-11-21 18:25:47 +01:00 · 2025-11-21 18:18:30 +01:00
593 changed files with 50906 additions and 11611 deletions
@@ -8,10 +8,13 @@ on:
      - 'gateway/**'
      - 'integrations/**'
      - 'nym-api/**'
+      - 'nym-authenticator-client/**'
      - 'nym-credential-proxy/**'
+      - 'nym-ip-packet-client/**'
      - 'nym-network-monitor/**'
      - 'nym-node/**'
      - 'nym-node-status-api/**'
+      - 'nym-registration-client/**'
      - 'nym-statistics-api/**'
      - 'nym-outfox/**'
      - 'nym-validator-rewarder/**'
@@ -6,16 +6,14 @@ on:
    paths:
      - "ts-packages/**"
      - "sdk/typescript/**"
-      - "nym-connect/desktop/src/**"
-      - "nym-connect/desktop/package.json"
      - "nym-wallet/src/**"
      - "nym-wallet/package.json"
-      - "explorer/**"
+      - "explorer-v2/**"
      - ".github/workflows/ci-lint-typescript.yml"

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

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

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

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

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

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

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

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

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

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

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

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

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

      - name: Install dependencies
        run: yarn
@@ -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
@@ -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
@@ -63,3 +63,6 @@ nym-api/redocly/formatted-openapi.json

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

 ## [Unreleased]

+## [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])
@@ -1,686 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Nym is a privacy platform that uses mixnet technology to protect against metadata surveillance. The platform consists of several key components:
- Mixnet nodes (mixnodes) for packet mixing
- Gateways (entry/exit points for the network)
- Clients for interacting with the network
- Network monitoring tools
- Validators for network consensus
- Various service providers and integrations
-
-## Build Commands
-
-### Rust Components
-
-```bash
-# Default build (debug)
-cargo build
-
-# Release build
-cargo build --release
-
-# Build a specific package
-cargo build -p <package-name>
-
-# Build main components
-make build
-
-# Build release versions of main binaries and contracts
-make build-release
-
-# Build specific binaries
-make build-nym-cli
-cargo build -p nym-node --release
-cargo build -p nym-api --release
-```
-
-### Testing
-
-```bash
-# Run clippy, unit tests, and formatting
-make test
-
-# Run all tests including slow tests
-make test-all
-
-# Run clippy on all workspaces
-make clippy
-
-# Run unit tests for a specific package
-cargo test -p <package-name>
-
-# Run only expensive/ignored tests
-cargo test --workspace -- --ignored
-
-# Run API tests
-dotenv -f envs/sandbox.env -- cargo test --test public-api-tests
-
-# Run tests with specific log level
-RUST_LOG=debug cargo test -p <package-name>
-
-# Run specific test scripts
-./nym-node/tests/test_apis.sh
-./scripts/wireguard-exit-policy/exit-policy-tests.sh
-```
-
-### Linting and Formatting
-
-```bash
-# Run rustfmt on all code
-make fmt
-
-# Check formatting without modifying
-cargo fmt --all -- --check
-
-# Run clippy with all targets
-cargo clippy --workspace --all-targets -- -D warnings
-
-# TypeScript linting
-yarn lint
-yarn lint:fix
-yarn types:lint:fix
-
-# Check dependencies for security/licensing issues
-cargo deny check
-```
-
-### WASM Components
-
-```bash
-# Build all WASM components
-make sdk-wasm-build
-
-# Build TypeScript SDK
-yarn build:sdk
-npx lerna run --scope @nymproject/sdk build --stream
-
-# Build and test WASM components
-make sdk-wasm
-
-# Build specific WASM packages
-cd wasm/client && make
-cd wasm/mix-fetch && make
-cd wasm/node-tester && make
-```
-
-### Contract Development
-
-```bash
-# Build all contracts
-make contracts
-
-# Build contracts in release mode
-make build-release-contracts
-
-# Generate contract schemas
-make contract-schema
-
-# Run wasm-opt on contracts
-make wasm-opt-contracts
-
-# Check contracts with cosmwasm-check
-make cosmwasm-check-contracts
-```
-
-### Running Components
-
-```bash
-# Run nym-node as a mixnode
-cargo run -p nym-node -- run --mode mixnode
-
-# Run nym-node as a gateway
-cargo run -p nym-node -- run --mode gateway
-
-# Run the network monitor
-cargo run -p nym-network-monitor
-
-# Run the API server
-cargo run -p nym-api
-
-# Run with specific environment
-dotenv -f envs/sandbox.env -- cargo run -p nym-api
-
-# Start a local network
-./scripts/localnet_start.sh
-```
-
-## Architecture
-
-The Nym platform consists of various components organized as a monorepo:
-
-1. **Core Mixnet Infrastructure**:
-   - `nym-node`: Core binary supporting mixnode and gateway modes
-   - `common/nymsphinx`: Implementation of the Sphinx packet format
-   - `common/topology`: Network topology management
-   - `common/types`: Shared data types across components
-
-2. **Network Monitoring**:
-   - `nym-network-monitor`: Monitors the network's reliability and performance
-   - `nym-api`: API server for network stats and monitoring data
-   - Metrics tracking for nodes, routes, and overall network health
-
-3. **Client Implementations**:
-   - `clients/native`: Native Rust client implementation
-   - `clients/socks5`: SOCKS5 proxy client for standard applications
-   - `wasm`: WebAssembly client implementations (for browsers)
-   - `nym-connect`: Desktop and mobile clients
-
-4. **Blockchain & Smart Contracts**:
-   - `common/cosmwasm-smart-contracts`: Smart contract implementations
-   - `contracts`: CosmWasm contracts for the Nym network
-   - `common/ledger`: Blockchain integration
-
-5. **Utilities & Tools**:
-   - `tools`: Various CLI tools and utilities
-   - `sdk`: SDKs for different languages and platforms
-   - `documentation`: Documentation generation and management
-
-## Packet System
-
-Nym uses a modified Sphinx packet format for its mixnet:
-
-1. **Message Chunking**:
-   - Messages are divided into "sets" and "fragments"
-   - Each fragment fits in a single Sphinx packet
-   - The `common/nymsphinx/chunking` module handles message fragmentation
-
-2. **Routing**:
-   - Packets traverse through 3 layers of mixnodes
-   - Routing information is encrypted in layers (onion routing)
-   - The final gateway receives and processes the messages
-
-3. **Monitoring**:
-   - Monitoring system tracks packet delivery through the network
-   - Routes are analyzed for reliability statistics
-   - Node performance metrics are collected
-
-## Network Protocol
-
-Nym implements the Loopix mixnet design with several key privacy features:
-
-1. **Continuous-time Mixing**:
-   - Each mixnode delays messages independently with an exponential distribution
-   - This creates random reordering of packets, destroying timing correlations
-   - Offers better anonymity properties than batch mixing approaches
-
-2. **Cover Traffic**:
-   - Clients and nodes generate dummy "loop" packets that circulate through the network
-   - These packets are indistinguishable from real traffic
-   - Creates a baseline level of traffic that hides actual communication patterns
-   - Provides unobservability (hiding when and how much real traffic is being sent)
-
-3. **Stratified Network Architecture**:
-   - Traffic flows through Entry Gateway → 3 Mixnode Layers → Exit Gateway
-   - Path selection is independent per-message (unlike Tor)
-   - Each node connects only to adjacent layers
-
-4. **Anonymous Replies**:
-   - Single-Use Reply Blocks (SURBs) allow receiving messages without revealing identity
-   - Enables bidirectional communication while maintaining privacy
-
-## Network Monitoring Architecture
-
-The network monitoring system is a core component that measures mixnet reliability:
-
-1. The `nym-network-monitor` sends test packets through the network
-2. These packets follow predefined routes through multiple mixnodes
-3. Metrics are collected about:
-   - Successful and failed packet deliveries
-   - Node reliability (percentage of successful packet handling)
-   - Route reliability (which specific route combinations work best)
-4. Results are stored in the database and used by `nym-api` to:
-   - Present node performance statistics
-   - Determine network rewards
-   - Provide route selection guidance to clients
-
-In the current branch, metrics collection is being enhanced with a fanout approach to submit to multiple API endpoints.
-
-## Development Environment
-
-### Required Dependencies
-
- Rust toolchain (stable, 1.80+)
- Node.js (v20+) and yarn for TypeScript components
- SQLite for local database development
- PostgreSQL for API database (optional, for full API functionality)
- CosmWasm tools for contract development
- For building contracts: `wasm-opt` tool from `binaryen`
- Python 3.8+ for some scripts
- Docker (optional, for containerized development)
- protoc (Protocol Buffers compiler) for some components
-
-### Environment Configurations
-
-The `envs/` directory contains pre-configured environments:
-
-#### Available Environments
-
- **`local.env`**: Local development environment
-  - Points to local services (localhost)
-  - Uses test mnemonics and keys
-  - Ideal for testing without external dependencies
-
- **`sandbox.env`**: Sandbox test network
-  - Public test network with real nodes
-  - Test tokens available from faucet
-  - Contract addresses for sandbox deployment
-  - API: https://sandbox-nym-api1.nymtech.net
-
- **`mainnet.env`**: Production mainnet
-  - Real network with real tokens
-  - Production contract addresses
-  - API: https://validator.nymtech.net
-  - Use with caution!
-
- **`canary.env`**: Canary deployment
-  - Pre-release testing environment
-  - Tests new features before mainnet
-
- **`mainnet-local-api.env`**: Hybrid environment
-  - Uses mainnet contracts but local API
-  - Useful for API development against mainnet data
-
-#### Key Environment Variables
-
-```bash
-# Network configuration
-NETWORK_NAME=sandbox              # Network identifier
-BECH32_PREFIX=n                   # Address prefix (n for sandbox, n for mainnet)
-NYM_API=https://sandbox-nym-api1.nymtech.net/api
-NYXD=https://rpc.sandbox.nymtech.net
-NYM_API_NETWORK=sandbox
-
-# Contract addresses (network-specific)
-MIXNET_CONTRACT_ADDRESS=n1xr3rq8yvd7qplsw5yx90ftsr2zdhg4e9z60h5duusgxpv72hud3sjkxkav
-VESTING_CONTRACT_ADDRESS=n1unyuj8qnmygvzuex3dwmg9yzt9alhvyeat0uu0jedg2wj33efl5qackslz
-# ... other contract addresses
-
-# Mnemonic for testing (NEVER use in production)
-MNEMONIC="clutch captain shoe salt awake harvest setup primary inmate ugly among become"
-
-# API Keys and tokens
-IPINFO_API_TOKEN=your_token_here
-AUTHENTICATOR_PASSWORD=password_here
-
-# Logging
-RUST_LOG=info                    # Options: error, warn, info, debug, trace
-RUST_BACKTRACE=1                # Enable backtraces
-
-# Database
-DATABASE_URL=postgresql://user:pass@localhost/nym_api
-```
-
-#### Using Environment Files
-
-```bash
-# Load environment and run command
-dotenv -f envs/sandbox.env -- cargo run -p nym-api
-
-# Export to shell
-source envs/sandbox.env
-
-# Use with make targets
-dotenv -f envs/sandbox.env -- make run-api-tests
-```
-
-## Initial Setup
-
-### First Time Setup
-
-1. **Install Prerequisites**
-   ```bash
-   # Install Rust
-   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-   
-   # Install Node.js and yarn
-   # Via nvm (recommended):
-   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
-   nvm install 20
-   npm install -g yarn
-   
-   # Install build tools
-   # Ubuntu/Debian:
-   sudo apt-get install build-essential pkg-config libssl-dev protobuf-compiler libpq-dev
-   
-   # macOS:
-   brew install protobuf postgresql
-   
-   # Install wasm-opt for contract builds
-   npm install -g wasm-opt
-   
-   # Add wasm target for Rust
-   rustup target add wasm32-unknown-unknown
-   ```
-
-2. **Clone and Setup Repository**
-   ```bash
-   git clone https://github.com/nymtech/nym.git
-   cd nym/nym
-   
-   # Install JavaScript dependencies
-   yarn install
-   
-   # Build the project
-   make build
-   ```
-
-3. **Database Setup (Optional, for API development)**
-   ```bash
-   # Install PostgreSQL
-   # Create database
-   createdb nym_api
-   
-   # Run migrations (from nym-api directory)
-   cd nym-api
-   sqlx migrate run
-   ```
-
-### Quick Start
-
-```bash
-# Run a mixnode locally
-dotenv -f envs/sandbox.env -- cargo run -p nym-node -- run --mode mixnode --id my-mixnode
-
-# Run a gateway locally
-dotenv -f envs/sandbox.env -- cargo run -p nym-node -- run --mode gateway --id my-gateway
-
-# Run the API server
-dotenv -f envs/sandbox.env -- cargo run -p nym-api
-
-# Run a client
-cargo run -p nym-client -- init --id my-client
-cargo run -p nym-client -- run --id my-client
-```
-
-## CI/CD Pipeline
-
-The project uses GitHub Actions for CI/CD with several key workflows:
-
-1. **Build and Test**:
-   - `ci-build.yml`: Main build workflow for Rust components
-   - Tests are run on multiple platforms (Linux, Windows, macOS)
-   - Includes formatting check (rustfmt) and linting (clippy)
-
-2. **Release Process**:
-   - Binary artifacts are published on release tags
-   - Multiple platform builds are created
-
-3. **Documentation**:
-   - Documentation is automatically built and deployed
-
-## Database Structure
-
-The system uses SQLite databases with tables like:
- `mixnode_status`: Status information about mixnodes
- `gateway_status`: Status information about gateways
- `routes`: Route performance information (success/failure of specific paths)
- `monitor_run`: Information about monitoring test runs
-
-## Development Workflows
-
-### Running a Node
-
-To run the mixnode or gateway:
-
-```bash
-# Run nym-node as a mixnode with specified identity
-cargo run -p nym-node -- run --mode mixnode --id my-mixnode
-
-# Run nym-node as a gateway
-cargo run -p nym-node -- run --mode gateway --id my-gateway
-```
-
-### Configuration
-
-Nodes can be configured with files in various locations:
- Command-line arguments
- Environment variables
- `.env` files specified with `--config-env-file`
-
-### Monitoring
-
-To monitor the health of your node:
- View logs for real-time information
- Use the node's HTTP API for status information
- Check the explorer for public node statistics
-
-## Common Libraries
-
- `common/types`: Shared data types across all components
- `common/crypto`: Cryptographic primitives and wrappers
- `common/client-core`: Core client functionality
- `common/gateway-client`: Client-gateway communication
- `common/task`: Task management and concurrency utilities
- `common/nymsphinx`: Sphinx packet implementation for mixnet
- `common/topology`: Network topology management
- `common/credentials`: Credential system for privacy-preserving authentication
- `common/bandwidth-controller`: Bandwidth management and accounting
-
-## Code Conventions
-
- Error handling: Use anyhow/thiserror for structured error handling
- Logging: Use the tracing framework for logging and diagnostics
- State management: Generally use Tokio/futures for async code
- Configuration: Use the config crate and env vars with defaults
- Database: Use sqlx for type-safe database queries
- Follow clippy recommendations and rustfmt formatting
- Use semantic commit messages: feat, fix, docs, refactor, test, chore
-
-## When Making Changes
-
- Run `make test` before submitting PRs
- Follow Rust naming conventions
- Use `clippy` to check for common issues
- Update SQLx query caches when modifying DB queries: `cargo sqlx prepare`
- Consider backward compatibility for protocol changes
- Use lefthook pre-commit hooks for TypeScript formatting
- Run `cargo deny check` to verify dependency compliance
- Test against both sandbox and local environments when possible
- Update relevant documentation and CHANGELOG.md
-
-## Development Tools
-
-### Useful Cargo Commands
-
-```bash
-# Check for outdated dependencies
-cargo outdated
-
-# Analyze binary size
-cargo bloat --release -p nym-node
-
-# Generate dependency graph
-cargo tree -p nym-api
-
-# Run with instrumentation
-cargo run --features profiling -p nym-node
-
-# Check for security advisories
-cargo audit
-```
-
-### Database Tools
-
-```bash
-# SQLx CLI for migrations
-cargo install sqlx-cli
-
-# Create new migration
-cd nym-api && sqlx migrate add <migration_name>
-
-# Prepare query metadata for offline compilation
-cargo sqlx prepare --workspace
-
-# View database schema
-./nym-api/enter_db.sh
-```
-
-### Development Scripts
-
- `scripts/build_topology.py`: Generate network topology files
- `scripts/node_api_check.py`: Verify node API endpoints
- `scripts/network_tunnel_manager.sh`: Manage network tunnels
- `scripts/localnet_start.sh`: Start a local test network
- Various deployment scripts in `deployment/` for different environments
-
-## Debugging
-
- Enable more verbose logging with the RUST_LOG environment variable:
-  ```
-  RUST_LOG=debug,nym_node=trace cargo run -p nym-node -- run --mode mixnode
-  ```
- Use the HTTP API endpoints for status information
- Check monitoring data in the database for network performance metrics
- For complex issues, use tracing tools to follow packet flow
- Enable backtraces: `RUST_BACKTRACE=full`
- For WASM debugging: Use browser developer tools with source maps
-
-## Deployment and Advanced Configurations
-
-### Deployment Structure
-
-The `deployment/` directory contains Ansible playbooks and configurations for various deployment scenarios:
-
- **`aws/`**: AWS-specific deployment configurations
- **`mixnode/`**: Mixnode deployment playbooks
- **`gateway/`**: Gateway deployment playbooks
- **`validator/`**: Validator node deployment
- **`sandbox-v2/`**: Complete sandbox environment setup
- **`big-dipper-2/`**: Block explorer deployment
-
-### Sandbox V2 Deployment
-
-The sandbox-v2 deployment (`deployment/sandbox-v2/`) provides a complete test environment:
-
-```bash
-# Key playbooks:
- deploy.yaml              # Main deployment orchestrator
- deploy-mixnodes.yaml    # Deploy mixnodes
- deploy-gateways.yaml    # Deploy gateways
- deploy-validators.yaml  # Deploy validator nodes
- deploy-nym-api.yaml     # Deploy API services
-```
-
-### Custom Environment Setup
-
-To create a custom environment:
-
-1. Copy an existing env file: `cp envs/sandbox.env envs/custom.env`
-2. Modify the network endpoints and contract addresses
-3. Update the `NETWORK_NAME` to your identifier
-4. Set appropriate mnemonics and keys (use fresh ones for production!)
-
-### Contract Addresses
-
-Contract addresses are network-specific and defined in environment files:
- Mixnet contract: Manages mixnode/gateway registry
- Vesting contract: Handles token vesting schedules
- Coconut contracts: Privacy-preserving credentials
- Name service: Human-readable address mapping
- Ecash contract: Electronic cash functionality
-
-### Local Network Setup
-
-For a completely local network:
-```bash
-# Start local chain
-./scripts/localnet_start.sh
-
-# Deploy contracts
-cd contracts
-make deploy-local
-
-# Start nodes with local config
-dotenv -f envs/local.env -- cargo run -p nym-node -- run --mode mixnode
-```
-
-## Common Issues and Troubleshooting
-
-### Database Issues
-
- When modifying database queries, you must update SQLx query caches:
-  ```bash
-  cargo sqlx prepare
-  ```
- If you see SQLx errors about missing query files, this is likely the cause
- For "database is locked" errors with SQLite, ensure only one process accesses the DB
- For PostgreSQL connection issues, verify DATABASE_URL and that the server is running
-
-### API Connection Issues
-
- Check the environment variables pointing to the APIs (NYM_API, NYXD)
- Verify network connectivity and API health endpoints
- For authentication issues, check node keys and credentials
- Common endpoints to verify:
-  - API health: `$NYM_API/health`
-  - Chain status: `$NYXD/status`
-  - Contract info: `$NYXD/cosmwasm/wasm/v1/contract/$CONTRACT_ADDRESS`
-
-### Build Problems
-
- Clean dependencies with `cargo clean` for a fresh build
- Check for compatible Rust version (1.80+ recommended)
- For smart contract builds, ensure wasm-opt is installed: `npm install -g wasm-opt`
- For cross-compilation issues, check target-specific dependencies
- WASM build issues: Ensure wasm32-unknown-unknown target is installed:
-  ```bash
-  rustup target add wasm32-unknown-unknown
-  ```
- For "cannot find -lpq" errors, install PostgreSQL development files:
-  ```bash
-  # Ubuntu/Debian
-  sudo apt-get install libpq-dev
-  # macOS
-  brew install postgresql
-  ```
-
-### Environment Issues
-
- Contract address mismatches: Ensure you're using the correct environment file
- "Account sequence mismatch": The account nonce is out of sync, wait and retry
- Token decimal issues: Sandbox uses different decimal places than mainnet
- API version mismatches: Ensure your local API version matches the network
- "Insufficient funds": Get test tokens from faucet (sandbox) or check balance
- Gateway/mixnode bonding issues: Verify minimum stake requirements
-
-## Working with Routes and Monitoring
-
-1. Route monitoring metrics are stored in a `routes` table with:
-   - Layer node IDs (layer1, layer2, layer3, gw)
-   - Success flag (boolean)
-   - Timestamp
-
-2. To analyze routes:
-   - Check `NetworkAccount` and `AccountingRoute` in `nym-network-monitor/src/accounting.rs`
-   - View monitoring logic in `common/nymsphinx/chunking/monitoring.rs`
-   - Observe how routes are submitted to the database in the `submit_accounting_routes_to_db` function
-
-## Performance Optimization
-
-### Profiling and Benchmarking
-
-```bash
-# Run benchmarks
-cargo bench -p nym-node
-
-# Profile with perf (Linux)
-cargo build --release --features profiling
-perf record --call-graph=dwarf ./target/release/nym-node run --mode mixnode
-perf report
-
-# Generate flamegraph
-cargo install flamegraph
-cargo flamegraph --bin nym-node -- run --mode mixnode
-```
-
-### Common Performance Considerations
-
- Use bounded channels for backpressure
- Batch database operations where possible
- Monitor memory usage with `RUST_LOG=nym_node::metrics=debug`
- Use connection pooling for database connections
- Consider using `jemalloc` for better memory allocation performance
@@ -165,6 +165,15 @@ version = "0.1.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4b46cbb362ab8752921c97e041f5e366ee6297bd428a31275b9fcf1e380f7299"

+[[package]]
+name = "ansi_term"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d52a9bb7ec0cf484c551830a7ce27bd20d67eac647e1befb56b0be4ee39a55d2"
+dependencies = [
+ "winapi",
+]
+
 [[package]]
 name = "anstream"
 version = "0.6.19"
@@ -991,6 +1000,12 @@ version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e3b5ca7a04898ad4bcd41c90c5285445ff5b791899bb1b0abdd2a2aa791211d7"

+[[package]]
+name = "byte_string"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11aade7a05aa8c3a351cedc44c3fc45806430543382fcc4743a9b757a2a0b4ed"
+
 [[package]]
 name = "bytecodec"
 version = "0.4.15"
@@ -1259,6 +1274,16 @@ version = "0.7.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b94f61472cee1439c0b966b47e3aca9ae07e45d070759512cd390ea2bebc6675"

+[[package]]
+name = "classic-mceliece-rust"
+version = "3.2.0"
+source = "git+https://github.com/georgio/classic-mceliece-rust#f2f27048b621df103bbe64369a18174ffec04ae1"
+dependencies = [
+ "rand 0.9.2",
+ "sha3",
+ "zeroize",
+]
+
 [[package]]
 name = "coarsetime"
 version = "0.1.36"
@@ -1432,6 +1457,16 @@ version = "0.8.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"

+[[package]]
+name = "core-models"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "hax-lib",
+ "pastey",
+ "rand 0.9.2",
+]
+
 [[package]]
 name = "cosmos-sdk-proto"
 version = "0.26.1"
@@ -1859,6 +1894,7 @@ dependencies = [
 "curve25519-dalek-derive",
 "digest 0.10.7",
 "fiat-crypto",
+ "rand_core 0.6.4",
 "rustc_version 0.4.1",
 "serde",
 "subtle 2.6.1",
@@ -2579,7 +2615,7 @@ dependencies = [

 [[package]]
 name = "extension-storage"
-version = "1.4.0-rc.0"
+version = "1.4.1"
 dependencies = [
 "bip39",
 "console_error_panic_hook",
@@ -3159,6 +3195,43 @@ dependencies = [
 "hashbrown 0.15.4",
 ]

+[[package]]
+name = "hax-lib"
+version = "0.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "74d9ba66d1739c68e0219b2b2238b5c4145f491ebf181b9c6ab561a19352ae86"
+dependencies = [
+ "hax-lib-macros",
+ "num-bigint",
+ "num-traits",
+]
+
+[[package]]
+name = "hax-lib-macros"
+version = "0.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24ba777a231a58d1bce1d68313fa6b6afcc7966adef23d60f45b8a2b9b688bf1"
+dependencies = [
+ "hax-lib-macros-types",
+ "proc-macro-error2",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.106",
+]
+
+[[package]]
+name = "hax-lib-macros-types"
+version = "0.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "867e19177d7425140b417cd27c2e05320e727ee682e98368f88b7194e80ad515"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "serde",
+ "serde_json",
+ "uuid",
+]
+
 [[package]]
 name = "hdrhistogram"
 version = "7.5.4"
@@ -4107,6 +4180,15 @@ dependencies = [
 "signature",
 ]

+[[package]]
+name = "keccak"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ecc2af9a1119c51f12a14607e783cb977bde58bc069ff0c3da1095e635d70654"
+dependencies = [
+ "cpufeatures",
+]
+
 [[package]]
 name = "keystream"
 version = "1.0.0"
@@ -4185,6 +4267,213 @@ version = "0.2.174"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1171693293099992e19cddea4e8b849964e9846f4acee11b3948bcc337be8776"

+[[package]]
+name = "libcrux-chacha20poly1305"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-macros",
+ "libcrux-poly1305",
+ "libcrux-secrets",
+ "libcrux-traits",
+]
+
+[[package]]
+name = "libcrux-curve25519"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-macros",
+ "libcrux-secrets",
+ "libcrux-traits",
+]
+
+[[package]]
+name = "libcrux-ecdh"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-curve25519",
+ "libcrux-p256",
+ "rand 0.9.2",
+ "tls_codec",
+]
+
+[[package]]
+name = "libcrux-ed25519"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-macros",
+ "libcrux-sha2",
+ "rand_core 0.9.3",
+ "tls_codec",
+]
+
+[[package]]
+name = "libcrux-hacl-rs"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-macros",
+]
+
+[[package]]
+name = "libcrux-hkdf"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-hmac",
+ "libcrux-secrets",
+]
+
+[[package]]
+name = "libcrux-hmac"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-macros",
+ "libcrux-sha2",
+]
+
+[[package]]
+name = "libcrux-intrinsics"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "core-models",
+ "hax-lib",
+]
+
+[[package]]
+name = "libcrux-kem"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-curve25519",
+ "libcrux-ecdh",
+ "libcrux-ml-kem",
+ "libcrux-p256",
+ "libcrux-sha3",
+ "libcrux-traits",
+ "rand 0.9.2",
+ "tls_codec",
+]
+
+[[package]]
+name = "libcrux-macros"
+version = "0.0.3"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "quote",
+ "syn 2.0.106",
+]
+
+[[package]]
+name = "libcrux-ml-kem"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "hax-lib",
+ "libcrux-intrinsics",
+ "libcrux-platform",
+ "libcrux-secrets",
+ "libcrux-sha3",
+ "libcrux-traits",
+ "rand 0.9.2",
+ "tls_codec",
+]
+
+[[package]]
+name = "libcrux-p256"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-macros",
+ "libcrux-secrets",
+ "libcrux-sha2",
+ "libcrux-traits",
+]
+
+[[package]]
+name = "libcrux-platform"
+version = "0.0.2"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "libcrux-poly1305"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-macros",
+]
+
+[[package]]
+name = "libcrux-psq"
+version = "0.0.5"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-chacha20poly1305",
+ "libcrux-ecdh",
+ "libcrux-ed25519",
+ "libcrux-hkdf",
+ "libcrux-hmac",
+ "libcrux-kem",
+ "libcrux-ml-kem",
+ "libcrux-sha2",
+ "libcrux-traits",
+ "rand 0.9.2",
+ "tls_codec",
+]
+
+[[package]]
+name = "libcrux-secrets"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "hax-lib",
+]
+
+[[package]]
+name = "libcrux-sha2"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-hacl-rs",
+ "libcrux-macros",
+ "libcrux-traits",
+]
+
+[[package]]
+name = "libcrux-sha3"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "hax-lib",
+ "libcrux-intrinsics",
+ "libcrux-platform",
+ "libcrux-traits",
+]
+
+[[package]]
+name = "libcrux-traits"
+version = "0.0.4"
+source = "git+https://github.com/cryspen/libcrux#f63bb67ead59297560edf523a3b29b21489c17ea"
+dependencies = [
+ "libcrux-secrets",
+ "rand 0.9.2",
+]
+
 [[package]]
 name = "libm"
 version = "0.2.15"
@@ -4478,7 +4767,7 @@ dependencies = [

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

+[[package]]
+name = "num_enum"
+version = "0.7.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1207a7e20ad57b847bbddc6776b968420d38292bbfe2089accff5e19e82454c"
+dependencies = [
+ "num_enum_derive",
+ "rustversion",
+]
+
+[[package]]
+name = "num_enum_derive"
+version = "0.7.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff32365de1b6743cb203b710788263c44a03de03802daf96092f2da4fe6ba4d7"
+dependencies = [
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.106",
+]
+
 [[package]]
 name = "num_threads"
 version = "0.1.7"
@@ -4824,7 +5136,7 @@ dependencies = [

 [[package]]
 name = "nym-api"
-version = "1.1.67"
+version = "1.1.69"
 dependencies = [
 "anyhow",
 "async-trait",
@@ -4987,6 +5299,7 @@ dependencies = [
 "nym-network-defaults",
 "nym-service-provider-requests-common",
 "nym-sphinx",
+ "nym-test-utils",
 "nym-wireguard-types",
 "rand 0.8.5",
 "semver 1.0.26",
@@ -4994,6 +5307,7 @@ dependencies = [
 "sha2 0.10.9",
 "strum_macros",
 "thiserror 2.0.12",
+ "tracing",
 "x25519-dalek",
 ]

@@ -5002,21 +5316,16 @@ name = "nym-bandwidth-controller"
 version = "0.1.0"
 dependencies = [
 "async-trait",
- "bip39",
 "log",
 "nym-credential-storage",
 "nym-credentials",
 "nym-credentials-interface",
 "nym-crypto",
- "nym-ecash-contract-common",
 "nym-ecash-time",
- "nym-network-defaults",
 "nym-task",
 "nym-validator-client",
 "rand 0.8.5",
 "thiserror 2.0.12",
- "url",
- "zeroize",
 ]

 [[package]]
@@ -5050,7 +5359,7 @@ dependencies = [

 [[package]]
 name = "nym-cli"
-version = "1.1.64"
+version = "1.1.66"
 dependencies = [
 "anyhow",
 "base64 0.22.1",
@@ -5133,7 +5442,7 @@ dependencies = [

 [[package]]
 name = "nym-client"
-version = "1.1.64"
+version = "1.1.66"
 dependencies = [
 "bs58",
 "clap",
@@ -5283,7 +5592,7 @@ dependencies = [

 [[package]]
 name = "nym-client-wasm"
-version = "1.4.0-rc.0"
+version = "1.4.1"
 dependencies = [
 "anyhow",
 "futures",
@@ -5462,8 +5771,11 @@ dependencies = [
 "nym-crypto",
 "nym-ecash-contract-common",
 "nym-ecash-signer-check",
+ "nym-http-api-client",
 "nym-http-api-common",
 "nym-network-defaults",
+ "nym-pemstore",
+ "nym-upgrade-mode-check",
 "nym-validator-client",
 "rand 0.8.5",
 "reqwest 0.12.22",
@@ -5534,6 +5846,7 @@ dependencies = [
 "nym-http-api-client",
 "nym-http-api-common",
 "nym-serde-helpers",
+ "nym-upgrade-mode-check",
 "reqwest 0.12.22",
 "schemars 0.8.22",
 "serde",
@@ -5565,6 +5878,7 @@ dependencies = [
 "sqlx",
 "sqlx-pool-guard",
 "thiserror 2.0.12",
+ "time",
 "tokio",
 "zeroize",
 ]
@@ -5600,12 +5914,14 @@ dependencies = [
 "nym-api-requests",
 "nym-credentials",
 "nym-credentials-interface",
+ "nym-crypto",
 "nym-ecash-contract-common",
 "nym-gateway-requests",
 "nym-gateway-storage",
+ "nym-metrics",
 "nym-task",
+ "nym-upgrade-mode-check",
 "nym-validator-client",
- "rand 0.8.5",
 "si-scale",
 "thiserror 2.0.12",
 "time",
@@ -5645,6 +5961,7 @@ dependencies = [
 "nym-compact-ecash",
 "nym-ecash-time",
 "nym-network-defaults",
+ "nym-upgrade-mode-check",
 "rand 0.8.5",
 "serde",
 "strum",
@@ -5661,11 +5978,13 @@ dependencies = [
 "aead",
 "aes",
 "aes-gcm-siv",
+ "anyhow",
 "base64 0.22.1",
 "blake3",
 "bs58",
 "cipher",
 "ctr",
+ "curve25519-dalek",
 "digest 0.10.7",
 "ed25519-dalek",
 "generic-array 0.14.7",
@@ -5674,10 +5993,12 @@ dependencies = [
 "jwt-simple",
 "nym-pemstore",
 "nym-sphinx-types",
+ "nym-test-utils",
 "rand 0.8.5",
 "rand_chacha 0.3.1",
 "serde",
 "serde_bytes",
+ "serde_json",
 "sha2 0.10.9",
 "subtle-encoding",
 "thiserror 2.0.12",
@@ -5792,18 +6113,17 @@ dependencies = [
 name = "nym-gateway"
 version = "1.1.36"
 dependencies = [
- "anyhow",
 "async-trait",
 "bincode",
 "bip39",
 "bs58",
+ "bytes",
 "dashmap",
 "defguard_wireguard_rs",
 "fastrand 2.3.0",
 "futures",
 "ipnetwork",
 "mock_instant",
- "nym-api-requests",
 "nym-authenticator-requests",
 "nym-client-core",
 "nym-credential-verification",
@@ -5815,31 +6135,32 @@ dependencies = [
 "nym-gateway-storage",
 "nym-id",
 "nym-ip-packet-router",
+ "nym-kcp",
+ "nym-lp",
+ "nym-metrics",
 "nym-mixnet-client",
- "nym-mixnode-common",
 "nym-network-defaults",
 "nym-network-requester",
 "nym-node-metrics",
+ "nym-registration-common",
 "nym-sdk",
 "nym-service-provider-requests-common",
 "nym-sphinx",
 "nym-statistics-common",
 "nym-task",
 "nym-topology",
- "nym-types",
+ "nym-upgrade-mode-check",
 "nym-validator-client",
 "nym-wireguard",
 "nym-wireguard-private-metadata-server",
 "nym-wireguard-types",
 "rand 0.8.5",
 "serde",
- "sha2 0.10.9",
 "thiserror 2.0.12",
 "time",
 "tokio",
 "tokio-stream",
 "tokio-tungstenite",
- "tokio-util",
 "tracing",
 "url",
 "zeroize",
@@ -5895,6 +6216,7 @@ dependencies = [
 "clap",
 "futures",
 "hex",
+ "nym-api-requests",
 "nym-authenticator-client",
 "nym-authenticator-requests",
 "nym-bandwidth-controller",
@@ -5910,7 +6232,13 @@ dependencies = [
 "nym-http-api-client-macro",
 "nym-ip-packet-client",
 "nym-ip-packet-requests",
+ "nym-lp",
+ "nym-mixnet-contract-common",
+ "nym-network-defaults",
+ "nym-node-requests",
 "nym-node-status-client",
+ "nym-registration-client",
+ "nym-registration-common",
 "nym-sdk",
 "nym-topology",
 "nym-validator-client",
@@ -5919,6 +6247,7 @@ dependencies = [
 "serde",
 "serde_json",
 "thiserror 2.0.12",
+ "time",
 "tokio",
 "tokio-util",
 "tracing",
@@ -6050,6 +6379,7 @@ dependencies = [
 "thiserror 2.0.12",
 "tokio",
 "tracing",
+ "tracing-subscriber",
 "url",
 "wasmtimer",
 ]
@@ -6200,6 +6530,48 @@ dependencies = [
 "url",
 ]

+[[package]]
+name = "nym-kcp"
+version = "0.1.0"
+dependencies = [
+ "ansi_term",
+ "byte_string",
+ "bytes",
+ "env_logger",
+ "log",
+ "thiserror 2.0.12",
+ "tokio-util",
+]
+
+[[package]]
+name = "nym-kkt"
+version = "0.1.0"
+dependencies = [
+ "aead",
+ "arc-swap",
+ "blake3",
+ "bytes",
+ "classic-mceliece-rust",
+ "criterion",
+ "curve25519-dalek",
+ "futures",
+ "libcrux-ecdh",
+ "libcrux-kem",
+ "libcrux-ml-kem",
+ "libcrux-psq",
+ "libcrux-sha3",
+ "libcrux-traits",
+ "nym-crypto",
+ "pin-project",
+ "rand 0.9.2",
+ "strum",
+ "thiserror 2.0.12",
+ "tokio",
+ "tokio-util",
+ "tracing",
+ "zeroize",
+]
+
 [[package]]
 name = "nym-ledger"
 version = "0.1.0"
@@ -6211,6 +6583,41 @@ dependencies = [
 "thiserror 2.0.12",
 ]

+[[package]]
+name = "nym-lp"
+version = "0.1.0"
+dependencies = [
+ "ansi_term",
+ "bincode",
+ "bs58",
+ "bytes",
+ "criterion",
+ "dashmap",
+ "libcrux-kem",
+ "libcrux-psq",
+ "libcrux-traits",
+ "num_enum",
+ "nym-crypto",
+ "nym-kkt",
+ "nym-lp-common",
+ "nym-sphinx",
+ "parking_lot",
+ "rand 0.8.5",
+ "rand 0.9.2",
+ "rand_chacha 0.3.1",
+ "serde",
+ "sha2 0.10.9",
+ "snow",
+ "thiserror 2.0.12",
+ "tls_codec",
+ "tracing",
+ "utoipa",
+]
+
+[[package]]
+name = "nym-lp-common"
+version = "0.1.0"
+
 [[package]]
 name = "nym-metrics"
 version = "0.1.0"
@@ -6354,7 +6761,7 @@ dependencies = [

 [[package]]
 name = "nym-network-requester"
-version = "1.1.65"
+version = "1.1.67"
 dependencies = [
 "addr",
 "anyhow",
@@ -6404,7 +6811,7 @@ dependencies = [

 [[package]]
 name = "nym-node"
-version = "1.19.0"
+version = "1.21.0"
 dependencies = [
 "anyhow",
 "arc-swap",
@@ -6435,6 +6842,7 @@ dependencies = [
 "nym-bin-common",
 "nym-client-core-config-types",
 "nym-config",
+ "nym-credential-verification",
 "nym-crypto",
 "nym-gateway",
 "nym-gateway-stats-storage",
@@ -6507,13 +6915,13 @@ version = "0.1.0"
 dependencies = [
 "async-trait",
 "celes",
- "humantime",
 "humantime-serde",
 "nym-bin-common",
 "nym-crypto",
 "nym-exit-policy",
 "nym-http-api-client",
 "nym-noise-keys",
+ "nym-upgrade-mode-check",
 "nym-wireguard-types",
 "rand_chacha 0.3.1",
 "schemars 0.8.22",
@@ -6524,6 +6932,7 @@ dependencies = [
 "thiserror 2.0.12",
 "time",
 "tokio",
+ "url",
 "utoipa",
 ]

@@ -6642,7 +7051,7 @@ dependencies = [

 [[package]]
 name = "nym-node-tester-wasm"
-version = "1.3.0-rc.0"
+version = "1.3.1"
 dependencies = [
 "futures",
 "js-sys",
@@ -6785,15 +7194,21 @@ dependencies = [
 name = "nym-registration-client"
 version = "0.1.0"
 dependencies = [
+ "bincode",
+ "bytes",
 "futures",
 "nym-authenticator-client",
 "nym-bandwidth-controller",
 "nym-credential-storage",
 "nym-credentials-interface",
+ "nym-crypto",
 "nym-ip-packet-client",
+ "nym-lp",
 "nym-registration-common",
 "nym-sdk",
 "nym-validator-client",
+ "nym-wireguard-types",
+ "rand 0.8.5",
 "thiserror 2.0.12",
 "tokio",
 "tokio-util",
@@ -6806,10 +7221,15 @@ dependencies = [
 name = "nym-registration-common"
 version = "0.1.0"
 dependencies = [
+ "bincode",
 "nym-authenticator-requests",
+ "nym-credentials-interface",
 "nym-crypto",
 "nym-ip-packet-requests",
 "nym-sphinx",
+ "nym-wireguard-types",
+ "serde",
+ "time",
 "tokio-util",
 ]

@@ -6931,7 +7351,7 @@ dependencies = [

 [[package]]
 name = "nym-socks5-client"
-version = "1.1.64"
+version = "1.1.66"
 dependencies = [
 "bs58",
 "clap",
@@ -7378,12 +7798,14 @@ dependencies = [
 "jwt-simple",
 "nym-crypto",
 "nym-http-api-client",
+ "nym-test-utils",
 "reqwest 0.12.22",
 "serde",
 "serde_json",
 "thiserror 2.0.12",
 "time",
 "tracing",
+ "utoipa",
 ]

 [[package]]
@@ -7563,32 +7985,28 @@ dependencies = [
 name = "nym-wireguard"
 version = "0.1.0"
 dependencies = [
- "async-trait",
 "base64 0.22.1",
- "bincode",
- "chrono",
- "dashmap",
 "defguard_wireguard_rs",
- "dyn-clone",
 "futures",
 "ip_network",
+ "ipnetwork",
 "log",
- "nym-authenticator-requests",
 "nym-credential-verification",
 "nym-credentials-interface",
 "nym-crypto",
 "nym-gateway-requests",
 "nym-gateway-storage",
+ "nym-ip-packet-requests",
+ "nym-metrics",
 "nym-network-defaults",
 "nym-node-metrics",
 "nym-task",
 "nym-wireguard-types",
+ "rand 0.8.5",
 "thiserror 2.0.12",
- "time",
 "tokio",
 "tokio-stream",
 "tracing",
- "x25519-dalek",
 ]

 [[package]]
@@ -7640,15 +8058,20 @@ version = "1.0.0"
 dependencies = [
 "async-trait",
 "axum",
+ "futures",
 "nym-credential-verification",
 "nym-credentials-interface",
+ "nym-crypto",
 "nym-http-api-client",
 "nym-http-api-common",
+ "nym-upgrade-mode-check",
 "nym-wireguard",
 "nym-wireguard-private-metadata-client",
 "nym-wireguard-private-metadata-server",
 "nym-wireguard-private-metadata-shared",
+ "time",
 "tokio",
+ "tower 0.5.2",
 "tower-http 0.5.2",
 "utoipa",
 ]
@@ -7658,10 +8081,7 @@ name = "nym-wireguard-types"
 version = "0.1.0"
 dependencies = [
 "base64 0.22.1",
- "log",
- "nym-config",
 "nym-crypto",
- "nym-network-defaults",
 "rand 0.8.5",
 "serde",
 "thiserror 2.0.12",
@@ -7670,7 +8090,7 @@ dependencies = [

 [[package]]
 name = "nymvisor"
-version = "0.1.29"
+version = "0.1.31"
 dependencies = [
 "anyhow",
 "bytes",
@@ -7824,9 +8244,9 @@ checksum = "d05e27ee213611ffe7d6348b942e8f942b37114c00cc03cec254295a4a17852e"

 [[package]]
 name = "openssl-sys"
-version = "0.9.109"
+version = "0.9.110"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "90096e2e47630d78b7d1c20952dc621f957103f8bc2c8359ec81290d75238571"
+checksum = "0a9f0075ba3c21b09f8e8b2026584b1d18d49388648f2fbbf3c97ea8deced8e2"
 dependencies = [
 "cc",
 "libc",
@@ -8024,6 +8444,12 @@ version = "1.0.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"

+[[package]]
+name = "pastey"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "35fb2e5f958ec131621fdd531e9fc186ed768cbe395337403ae56c17a74c68ec"
+
 [[package]]
 name = "peg"
 version = "0.8.5"
@@ -9769,6 +10195,16 @@ dependencies = [
 "digest 0.10.7",
 ]

+[[package]]
+name = "sha3"
+version = "0.10.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75872d278a8f37ef87fa0ddbda7802605cb18344497949862c0d4dcb291eba60"
+dependencies = [
+ "digest 0.10.7",
+ "keccak",
+]
+
 [[package]]
 name = "sharded-slab"
 version = "0.1.7"
@@ -10755,6 +11191,27 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"

+[[package]]
+name = "tls_codec"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0de2e01245e2bb89d6f05801c564fa27624dbd7b1846859876c7dad82e90bf6b"
+dependencies = [
+ "tls_codec_derive",
+ "zeroize",
+]
+
+[[package]]
+name = "tls_codec_derive"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d2e76690929402faae40aebdda620a2c0e25dd6d3b9afe48867dfd95991f4bd"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.106",
+]
+
 [[package]]
 name = "tokio"
 version = "1.47.1"
@@ -72,6 +72,10 @@ members = [
    "common/nym-cache",
    "common/nym-connection-monitor",
    "common/nym-id",
+    "common/nym-kcp",
+    "common/nym-lp",
+    "common/nym-lp-common",
+    "common/nym-kkt",
    "common/nym-metrics",
    "common/nym_offline_compact_ecash",
    "common/nymnoise",
@@ -150,7 +154,7 @@ members = [
    "tools/internal/contract-state-importer/importer-cli",
    "tools/internal/contract-state-importer/importer-contract",
    "tools/internal/mixnet-connectivity-check",
-    # "tools/internal/sdk-version-bump",
+    #    "tools/internal/sdk-version-bump",
    "tools/internal/ssl-inject",
    "tools/internal/testnet-manager",
    "tools/internal/testnet-manager/dkg-bypass-contract",
@@ -165,12 +169,13 @@ members = [
    "wasm/mix-fetch",
    "wasm/node-tester",
    "wasm/zknym-lib",
-    "nym-gateway-probe"
+    "nym-gateway-probe",
 ]

 default-members = [
    "clients/native",
    "clients/socks5",
+    "nym-authenticator-client",
    "nym-api",
    "nym-credential-proxy/nym-credential-proxy",
    "nym-node",
@@ -203,6 +208,7 @@ aes = "0.8.1"
 aes-gcm = "0.10.1"
 aes-gcm-siv = "0.11.1"
 ammonia = "4"
+ansi_term = "0.12"
 anyhow = "1.0.98"
 arc-swap = "1.7.1"
 argon2 = "0.5.0"
@@ -242,6 +248,7 @@ criterion = "0.5"
 csv = "1.3.1"
 ctr = "0.9.1"
 cupid = "0.6.1"
+curve25519-dalek = "4.1.3"
 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" }
@@ -281,7 +288,9 @@ inventory = "0.3.21"
 ip_network = "0.4.1"
 ipnetwork = "0.20"
 itertools = "0.14.0"
-jwt-simple = { version = "0.12.12", default-features = false, features = ["pure-rust"] }
+jwt-simple = { version = "0.12.12", default-features = false, features = [
+    "pure-rust",
+] }
 k256 = "0.13"
 lazy_static = "1.5.0"
 ledger-transport = "0.10.0"
@@ -291,6 +300,7 @@ mime = "0.3.17"
 moka = { version = "0.12", features = ["future"] }
 nix = "0.27.1"
 notify = "5.1.0"
+num_enum = "0.7.5"
 once_cell = "1.21.3"
 opentelemetry = "0.19.0"
 opentelemetry-jaeger = "0.18.0"
@@ -337,6 +347,7 @@ test-with = { version = "0.15.4", default-features = false }
 tempfile = "3.20"
 thiserror = "2.0"
 time = "0.3.41"
+tls_codec = "0.4.1"
 tokio = "1.47"
 tokio-postgres = "0.7"
 tokio-stream = "0.1.17"
@@ -453,6 +464,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"
@@ -107,16 +107,16 @@ sdk-wasm-build:
 	$(MAKE) -C nym-browser-extension/storage wasm-pack
 	$(MAKE) -C wasm/client
 	$(MAKE) -C wasm/node-tester
-	# $(MAKE) -C wasm/mix-fetch
+	$(MAKE) -C wasm/mix-fetch
 	$(MAKE) -C wasm/zknym-lib
 	# $(MAKE) -C wasm/full-nym-wasm

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

 # NOTE: These targets are part of the main workspace (but not as wasm32-unknown-unknown)
 WASM_CRATES = extension-storage nym-client-wasm nym-node-tester-wasm zknym-lib
@@ -1,6 +1,6 @@
 [package]
 name = "nym-client"
-version = "1.1.64"
+version = "1.1.66"
 authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
 description = "Implementation of the Nym Client"
 edition = "2021"
@@ -1,6 +1,6 @@
 [package]
 name = "nym-socks5-client"
-version = "1.1.64"
+version = "1.1.66"
 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"
@@ -16,6 +16,7 @@ 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"] }
@@ -29,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
@@ -6,9 +6,11 @@ use nym_wireguard_types::PeerPublicKey;

 use crate::{
    AuthenticatorVersion, Error,
-    latest::registration::IpPair,
-    traits::{FinalMessage, InitMessage, QueryBandwidthMessage, TopUpMessage, Versionable},
-    v2, v3, v4, v5,
+    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.
@@ -19,6 +21,293 @@ pub enum ClientMessage {
    Final(Box<dyn FinalMessage + Send + Sync + 'static>),
    Query(Box<dyn QueryBandwidthMessage + Send + Sync + 'static>),
    TopUp(Box<dyn TopUpMessage + Send + Sync + 'static>),
+    UpgradeModeCheck(Box<dyn UpgradeModeMessage + Send + Sync + 'static>),
+}
+
+pub struct SerialisedRequest {
+    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 {
@@ -27,7 +316,7 @@ impl ClientMessage {
        match self {
            Self::Final(msg) => msg.credential().is_some(),
            Self::TopUp(_) => true,
-            Self::Initial(_) | Self::Query(_) => false,
+            Self::Initial(_) | Self::Query(_) | Self::UpgradeModeCheck(_) => false,
        }
    }

@@ -37,208 +326,18 @@ impl ClientMessage {
            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<(Vec<u8>, u64), Error> {
+    pub fn bytes(&self, reply_to: Recipient) -> Result<SerialisedRequest, Error> {
        match self.version() {
-            AuthenticatorVersion::V1 => Err(Error::UnsupportedVersion),
-            AuthenticatorVersion::V2 => {
-                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((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(),
-                            },
-                            reply_to,
-                        );
-                        Ok((req.to_bytes()?, id))
-                    }
-                    ClientMessage::Query(query_message) => {
-                        let (req, id) = AuthenticatorRequest::new_query_request(
-                            query_message.pub_key(),
-                            reply_to,
-                        );
-                        Ok((req.to_bytes()?, id))
-                    }
-                    _ => Err(Error::UnsupportedMessage),
-                }
-            }
-            AuthenticatorVersion::V3 => {
-                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((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(),
-                            },
-                            reply_to,
-                        );
-                        Ok((req.to_bytes()?, id))
-                    }
-                    ClientMessage::Query(query_message) => {
-                        let (req, id) = AuthenticatorRequest::new_query_request(
-                            query_message.pub_key(),
-                            reply_to,
-                        );
-                        Ok((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((req.to_bytes()?, id))
-                    }
-                }
-            }
-            AuthenticatorVersion::V4 => {
-                use v4::{
-                    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((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)?,
-                                    }
-                                    .into(),
-                                    mac: ClientMac::new(final_message.gateway_client_mac()),
-                                },
-                                credential: final_message.credential(),
-                            },
-                            reply_to,
-                        );
-                        Ok((req.to_bytes()?, id))
-                    }
-                    ClientMessage::Query(query_message) => {
-                        let (req, id) = AuthenticatorRequest::new_query_request(
-                            query_message.pub_key(),
-                            reply_to,
-                        );
-                        Ok((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((req.to_bytes()?, id))
-                    }
-                }
-            }
-            AuthenticatorVersion::V5 => {
-                use v5::{
-                    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(),
-                        });
-                        Ok((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((req.to_bytes()?, id))
-                    }
-                    ClientMessage::Query(query_message) => {
-                        let (req, id) =
-                            AuthenticatorRequest::new_query_request(query_message.pub_key());
-                        Ok((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((req.to_bytes()?, id))
-                    }
-                }
-            }
+            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),
        }
    }
@@ -247,7 +346,7 @@ impl ClientMessage {
        use AuthenticatorVersion::*;
        match self.version() {
            V1 | V2 | V3 | V4 => false,
-            V5 => true,
+            V5 | V6 => true,
            UNKNOWN => true,
        }
    }
@@ -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)]
@@ -37,3 +38,13 @@ pub enum Error {
    #[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())
+    }
+}
@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

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

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

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

 impl From<v1::request::AuthenticatorRequest> for AuthenticatorRequest {
@@ -202,3 +209,45 @@ impl From<v5::request::AuthenticatorRequest> for AuthenticatorRequest {
        }
    }
 }
+
+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,
+                }
+            }
+        }
+    }
+}
@@ -1,11 +1,12 @@
 // 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,
+    TopUpBandwidthResponse, UpgradeModeStatus,
 };
-use crate::{v2, v3, v4, v5};
+use crate::{v2, v3, v4, v5, v6};

 #[derive(Debug)]
 pub enum AuthenticatorResponse {
@@ -13,6 +14,29 @@ pub enum AuthenticatorResponse {
    Registered(Box<dyn RegisteredResponse + Send + Sync + 'static>),
    RemainingBandwidth(Box<dyn RemainingBandwidthResponse + Send + Sync + 'static>),
    TopUpBandwidth(Box<dyn TopUpBandwidthResponse + Send + Sync + 'static>),
+    UpgradeMode(Box<dyn UpgradeModeStatus + Send + Sync + 'static>),
+}
+
+impl UpgradeModeStatus for AuthenticatorResponse {
+    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 {
@@ -28,6 +52,7 @@ impl Id for AuthenticatorResponse {
            AuthenticatorResponse::TopUpBandwidth(top_up_bandwidth_response) => {
                top_up_bandwidth_response.id()
            }
+            AuthenticatorResponse::UpgradeMode(upgrade_mode_response) => upgrade_mode_response.id(),
        }
    }
 }
@@ -104,3 +129,25 @@ impl From<v5::response::AuthenticatorResponse> for AuthenticatorResponse {
        }
    }
 }
+
+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))
+            }
+        }
+    }
+}
@@ -1,15 +1,15 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

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

 pub trait Versionable {
    fn version(&self) -> AuthenticatorVersion;
@@ -51,6 +51,12 @@ impl Versionable for v5::registration::InitMessage {
    }
 }

+impl Versionable for v6::registration::InitMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V6
+    }
+}
+
 impl Versionable for v2::registration::FinalMessage {
    fn version(&self) -> AuthenticatorVersion {
        AuthenticatorVersion::V2
@@ -75,6 +81,12 @@ impl Versionable for v5::registration::FinalMessage {
    }
 }

+impl Versionable for v6::registration::FinalMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V6
+    }
+}
+
 impl Versionable for PeerPublicKey {
    fn version(&self) -> AuthenticatorVersion {
        AuthenticatorVersion::V3
@@ -98,6 +110,158 @@ impl Versionable for v5::topup::TopUpMessage {
        AuthenticatorVersion::V5
    }
 }
+impl Versionable for v6::topup::TopUpMessage {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V6
+    }
+}
+
+impl Versionable for v6::upgrade_mode_check::UpgradeModeCheckRequest {
+    fn version(&self) -> AuthenticatorVersion {
+        AuthenticatorVersion::V6
+    }
+}
+
+pub trait UpgradeModeStatus: Id + fmt::Debug {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus;
+}
+
+impl UpgradeModeStatus for v1::response::PendingRegistrationResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v1::response::RegisteredResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v1::response::RemainingBandwidthResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v2::response::PendingRegistrationResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v2::response::RegisteredResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v2::response::RemainingBandwidthResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+impl UpgradeModeStatus for v3::response::PendingRegistrationResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v3::response::RegisteredResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v3::response::RemainingBandwidthResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v3::response::TopUpBandwidthResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v4::response::PendingRegistrationResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v4::response::RegisteredResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v4::response::RemainingBandwidthResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v4::response::TopUpBandwidthResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v5::response::PendingRegistrationResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v5::response::RegisteredResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v5::response::RemainingBandwidthResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v5::response::TopUpBandwidthResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        CurrentUpgradeModeStatus::Unknown
+    }
+}
+
+impl UpgradeModeStatus for v6::response::PendingRegistrationResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        self.upgrade_mode_enabled.into()
+    }
+}
+
+impl UpgradeModeStatus for v6::response::RegisteredResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        self.upgrade_mode_enabled.into()
+    }
+}
+
+impl UpgradeModeStatus for v6::response::RemainingBandwidthResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        self.upgrade_mode_enabled.into()
+    }
+}
+
+impl UpgradeModeStatus for v6::response::TopUpBandwidthResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        self.upgrade_mode_enabled.into()
+    }
+}
+
+impl UpgradeModeStatus for v6::response::UpgradeModeResponse {
+    fn upgrade_mode_status(&self) -> CurrentUpgradeModeStatus {
+        self.upgrade_mode_enabled.into()
+    }
+}

 pub trait InitMessage: Versionable + fmt::Debug {
    fn pub_key(&self) -> PeerPublicKey;
@@ -133,14 +297,20 @@ impl InitMessage for v5::registration::InitMessage {
    }
 }

+impl InitMessage for v6::registration::InitMessage {
+    fn pub_key(&self) -> PeerPublicKey {
+        self.pub_key
+    }
+}
+
 pub trait FinalMessage: Versionable + fmt::Debug {
    fn gateway_client_pub_key(&self) -> PeerPublicKey;
-    fn verify(&self, private_key: &PrivateKey, nonce: u64) -> Result<(), Error>;
+    fn verify(&self, private_key: &x25519::PrivateKey, nonce: u64) -> Result<(), Error>;
    fn private_ips(&self) -> IpPair;
    fn gateway_client_ipv4(&self) -> Option<Ipv4Addr>;
    fn gateway_client_ipv6(&self) -> Option<Ipv6Addr>;
    fn gateway_client_mac(&self) -> Vec<u8>;
-    fn credential(&self) -> Option<CredentialSpendingData>;
+    fn credential(&self) -> Option<BandwidthClaim>;
 }

 impl FinalMessage for v1::GatewayClient {
@@ -148,7 +318,7 @@ impl FinalMessage for v1::GatewayClient {
        self.pub_key
    }

-    fn verify(&self, private_key: &PrivateKey, nonce: u64) -> Result<(), Error> {
+    fn verify(&self, private_key: &x25519::PrivateKey, nonce: u64) -> Result<(), Error> {
        self.verify(private_key, nonce)
    }

@@ -171,7 +341,7 @@ impl FinalMessage for v1::GatewayClient {
        self.mac.to_vec()
    }

-    fn credential(&self) -> Option<CredentialSpendingData> {
+    fn credential(&self) -> Option<BandwidthClaim> {
        None
    }
 }
@@ -181,7 +351,7 @@ impl FinalMessage for v2::registration::FinalMessage {
        self.gateway_client.pub_key
    }

-    fn verify(&self, private_key: &PrivateKey, nonce: u64) -> Result<(), Error> {
+    fn verify(&self, private_key: &x25519::PrivateKey, nonce: u64) -> Result<(), Error> {
        self.gateway_client.verify(private_key, nonce)
    }

@@ -204,8 +374,12 @@ impl FinalMessage for v2::registration::FinalMessage {
        self.gateway_client.mac.to_vec()
    }

-    fn credential(&self) -> Option<CredentialSpendingData> {
-        self.credential.clone()
+    fn credential(&self) -> Option<BandwidthClaim> {
+        self.credential.clone().and_then(|c| {
+            c.try_into()
+                .inspect_err(|err| error!("credential conversion error: {err}"))
+                .ok()
+        })
    }
 }

@@ -214,7 +388,7 @@ impl FinalMessage for v3::registration::FinalMessage {
        self.gateway_client.pub_key
    }

-    fn verify(&self, private_key: &PrivateKey, nonce: u64) -> Result<(), Error> {
+    fn verify(&self, private_key: &x25519::PrivateKey, nonce: u64) -> Result<(), Error> {
        self.gateway_client.verify(private_key, nonce)
    }

@@ -237,8 +411,12 @@ impl FinalMessage for v3::registration::FinalMessage {
        self.gateway_client.mac.to_vec()
    }

-    fn credential(&self) -> Option<CredentialSpendingData> {
-        self.credential.clone()
+    fn credential(&self) -> Option<BandwidthClaim> {
+        self.credential.clone().and_then(|c| {
+            c.try_into()
+                .inspect_err(|err| error!("credential conversion error: {err}"))
+                .ok()
+        })
    }
 }

@@ -247,7 +425,42 @@ impl FinalMessage for v4::registration::FinalMessage {
        self.gateway_client.pub_key
    }

-    fn verify(&self, private_key: &PrivateKey, nonce: u64) -> Result<(), Error> {
+    fn verify(&self, private_key: &x25519::PrivateKey, nonce: u64) -> Result<(), Error> {
+        self.gateway_client.verify(private_key, nonce)
+    }
+
+    fn private_ips(&self) -> IpPair {
+        // v4 -> v5 -> v6
+        v5::registration::IpPair::from(self.gateway_client.private_ips).into()
+    }
+
+    fn gateway_client_ipv4(&self) -> Option<Ipv4Addr> {
+        Some(self.gateway_client.private_ips.ipv4)
+    }
+
+    fn gateway_client_ipv6(&self) -> Option<Ipv6Addr> {
+        Some(self.gateway_client.private_ips.ipv6)
+    }
+
+    fn gateway_client_mac(&self) -> Vec<u8> {
+        self.gateway_client.mac.to_vec()
+    }
+
+    fn credential(&self) -> Option<BandwidthClaim> {
+        self.credential.clone().and_then(|c| {
+            c.try_into()
+                .inspect_err(|err| error!("credential conversion error: {err}"))
+                .ok()
+        })
+    }
+}
+
+impl FinalMessage for v5::registration::FinalMessage {
+    fn gateway_client_pub_key(&self) -> PeerPublicKey {
+        self.gateway_client.pub_key
+    }
+
+    fn verify(&self, private_key: &x25519::PrivateKey, nonce: u64) -> Result<(), Error> {
        self.gateway_client.verify(private_key, nonce)
    }

@@ -267,17 +480,21 @@ impl FinalMessage for v4::registration::FinalMessage {
        self.gateway_client.mac.to_vec()
    }

-    fn credential(&self) -> Option<CredentialSpendingData> {
-        self.credential.clone()
+    fn credential(&self) -> Option<BandwidthClaim> {
+        self.credential.clone().and_then(|c| {
+            c.try_into()
+                .inspect_err(|err| error!("credential conversion error: {err}"))
+                .ok()
+        })
    }
 }

-impl FinalMessage for v5::registration::FinalMessage {
+impl FinalMessage for v6::registration::FinalMessage {
    fn gateway_client_pub_key(&self) -> PeerPublicKey {
        self.gateway_client.pub_key
    }

-    fn verify(&self, private_key: &PrivateKey, nonce: u64) -> Result<(), Error> {
+    fn verify(&self, private_key: &x25519::PrivateKey, nonce: u64) -> Result<(), Error> {
        self.gateway_client.verify(private_key, nonce)
    }

@@ -297,7 +514,7 @@ impl FinalMessage for v5::registration::FinalMessage {
        self.gateway_client.mac.to_vec()
    }

-    fn credential(&self) -> Option<CredentialSpendingData> {
+    fn credential(&self) -> Option<BandwidthClaim> {
        self.credential.clone()
    }
 }
@@ -347,10 +564,42 @@ impl TopUpMessage for v5::topup::TopUpMessage {
    }
 }

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

+impl Id for v1::response::PendingRegistrationResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
 impl Id for v2::response::PendingRegistrationResponse {
    fn id(&self) -> u64 {
        self.request_id
@@ -375,6 +624,18 @@ impl Id for v5::response::PendingRegistrationResponse {
    }
 }

+impl Id for v6::response::PendingRegistrationResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
+impl Id for v1::response::RegisteredResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
 impl Id for v2::response::RegisteredResponse {
    fn id(&self) -> u64 {
        self.request_id
@@ -399,6 +660,18 @@ impl Id for v5::response::RegisteredResponse {
    }
 }

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

+impl Id for v6::response::RemainingBandwidthResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
 impl Id for v3::response::TopUpBandwidthResponse {
    fn id(&self) -> u64 {
        self.request_id
@@ -441,11 +720,28 @@ impl Id for v5::response::TopUpBandwidthResponse {
    }
 }

-pub trait PendingRegistrationResponse: Id + fmt::Debug {
+impl Id for v6::response::TopUpBandwidthResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
+impl Id for v6::response::UpgradeModeResponse {
+    fn id(&self) -> u64 {
+        self.request_id
+    }
+}
+
+pub trait PendingRegistrationResponse: Id + UpgradeModeStatus + fmt::Debug {
    fn nonce(&self) -> u64;
-    fn verify(&self, gateway_key: &PrivateKey) -> std::result::Result<(), Error>;
+    fn verify(&self, gateway_key: &x25519::PrivateKey) -> Result<(), Error>;
    fn pub_key(&self) -> PeerPublicKey;
    fn private_ips(&self) -> IpPair;
+    fn finalise_registration(
+        &self,
+        private_key: &x25519::PrivateKey,
+        credential: Option<BandwidthClaim>,
+    ) -> Box<dyn FinalMessage + Send + Sync>;
 }

 impl PendingRegistrationResponse for v2::response::PendingRegistrationResponse {
@@ -453,7 +749,7 @@ impl PendingRegistrationResponse for v2::response::PendingRegistrationResponse {
        self.reply.nonce
    }

-    fn verify(&self, gateway_key: &PrivateKey) -> std::result::Result<(), Error> {
+    fn verify(&self, gateway_key: &x25519::PrivateKey) -> Result<(), Error> {
        self.reply.gateway_data.verify(gateway_key, self.nonce())
    }

@@ -464,6 +760,22 @@ impl PendingRegistrationResponse for v2::response::PendingRegistrationResponse {
    fn private_ips(&self) -> IpPair {
        self.reply.gateway_data.private_ip.into()
    }
+
+    fn finalise_registration(
+        &self,
+        private_key: &x25519::PrivateKey,
+        credential: Option<BandwidthClaim>,
+    ) -> Box<dyn FinalMessage + Send + Sync> {
+        Box::new(v2::registration::FinalMessage {
+            gateway_client: v2::registration::GatewayClient::new(
+                private_key,
+                self.pub_key().inner(),
+                self.private_ips().ipv4.into(),
+                self.nonce(),
+            ),
+            credential: credential.and_then(|b| b.credential.into_zk_nym().map(|c| *c)),
+        })
+    }
 }

 impl PendingRegistrationResponse for v3::response::PendingRegistrationResponse {
@@ -471,7 +783,7 @@ impl PendingRegistrationResponse for v3::response::PendingRegistrationResponse {
        self.reply.nonce
    }

-    fn verify(&self, gateway_key: &PrivateKey) -> std::result::Result<(), Error> {
+    fn verify(&self, gateway_key: &x25519::PrivateKey) -> Result<(), Error> {
        self.reply.gateway_data.verify(gateway_key, self.nonce())
    }

@@ -482,6 +794,22 @@ impl PendingRegistrationResponse for v3::response::PendingRegistrationResponse {
    fn private_ips(&self) -> IpPair {
        self.reply.gateway_data.private_ip.into()
    }
+
+    fn finalise_registration(
+        &self,
+        private_key: &x25519::PrivateKey,
+        credential: Option<BandwidthClaim>,
+    ) -> Box<dyn FinalMessage + Send + Sync> {
+        Box::new(v3::registration::FinalMessage {
+            gateway_client: v3::registration::GatewayClient::new(
+                private_key,
+                self.pub_key().inner(),
+                self.private_ips().ipv4.into(),
+                self.nonce(),
+            ),
+            credential: credential.and_then(|b| b.credential.into_zk_nym().map(|c| *c)),
+        })
+    }
 }

 impl PendingRegistrationResponse for v4::response::PendingRegistrationResponse {
@@ -489,7 +817,42 @@ impl PendingRegistrationResponse for v4::response::PendingRegistrationResponse {
        self.reply.nonce
    }

-    fn verify(&self, gateway_key: &PrivateKey) -> std::result::Result<(), Error> {
+    fn verify(&self, gateway_key: &x25519::PrivateKey) -> Result<(), Error> {
+        self.reply.gateway_data.verify(gateway_key, self.nonce())
+    }
+
+    fn pub_key(&self) -> PeerPublicKey {
+        self.reply.gateway_data.pub_key
+    }
+
+    fn private_ips(&self) -> IpPair {
+        // v4 -> v5 -> v6
+        v5::registration::IpPair::from(self.reply.gateway_data.private_ips).into()
+    }
+
+    fn finalise_registration(
+        &self,
+        private_key: &x25519::PrivateKey,
+        credential: Option<BandwidthClaim>,
+    ) -> Box<dyn FinalMessage + Send + Sync> {
+        Box::new(v4::registration::FinalMessage {
+            gateway_client: v4::registration::GatewayClient::new(
+                private_key,
+                self.pub_key().inner(),
+                self.reply.gateway_data.private_ips,
+                self.nonce(),
+            ),
+            credential: credential.and_then(|b| b.credential.into_zk_nym().map(|c| *c)),
+        })
+    }
+}
+
+impl PendingRegistrationResponse for v5::response::PendingRegistrationResponse {
+    fn nonce(&self) -> u64 {
+        self.reply.nonce
+    }
+
+    fn verify(&self, gateway_key: &x25519::PrivateKey) -> Result<(), Error> {
        self.reply.gateway_data.verify(gateway_key, self.nonce())
    }

@@ -500,14 +863,30 @@ impl PendingRegistrationResponse for v4::response::PendingRegistrationResponse {
    fn private_ips(&self) -> IpPair {
        self.reply.gateway_data.private_ips.into()
    }
+
+    fn finalise_registration(
+        &self,
+        private_key: &x25519::PrivateKey,
+        credential: Option<BandwidthClaim>,
+    ) -> Box<dyn FinalMessage + Send + Sync> {
+        Box::new(v5::registration::FinalMessage {
+            gateway_client: v5::registration::GatewayClient::new(
+                private_key,
+                self.pub_key().inner(),
+                self.reply.gateway_data.private_ips,
+                self.nonce(),
+            ),
+            credential: credential.and_then(|b| b.credential.into_zk_nym().map(|c| *c)),
+        })
+    }
 }

-impl PendingRegistrationResponse for v5::response::PendingRegistrationResponse {
+impl PendingRegistrationResponse for v6::response::PendingRegistrationResponse {
    fn nonce(&self) -> u64 {
        self.reply.nonce
    }

-    fn verify(&self, gateway_key: &PrivateKey) -> std::result::Result<(), Error> {
+    fn verify(&self, gateway_key: &x25519::PrivateKey) -> Result<(), Error> {
        self.reply.gateway_data.verify(gateway_key, self.nonce())
    }

@@ -518,9 +897,25 @@ impl PendingRegistrationResponse for v5::response::PendingRegistrationResponse {
    fn private_ips(&self) -> IpPair {
        self.reply.gateway_data.private_ips
    }
+
+    fn finalise_registration(
+        &self,
+        private_key: &x25519::PrivateKey,
+        credential: Option<BandwidthClaim>,
+    ) -> Box<dyn FinalMessage + Send + Sync> {
+        Box::new(v6::registration::FinalMessage {
+            gateway_client: v6::registration::GatewayClient::new(
+                private_key,
+                self.pub_key().inner(),
+                self.reply.gateway_data.private_ips,
+                self.nonce(),
+            ),
+            credential,
+        })
+    }
 }

-pub trait RegisteredResponse: Id + fmt::Debug {
+pub trait RegisteredResponse: Id + UpgradeModeStatus + fmt::Debug {
    fn private_ips(&self) -> IpPair;
    fn pub_key(&self) -> PeerPublicKey;
    fn wg_port(&self) -> u16;
@@ -555,7 +950,8 @@ impl RegisteredResponse for v3::response::RegisteredResponse {
 }
 impl RegisteredResponse for v4::response::RegisteredResponse {
    fn private_ips(&self) -> IpPair {
-        self.reply.private_ips.into()
+        // v4 -> v5 -> v6
+        v5::registration::IpPair::from(self.reply.private_ips).into()
    }

    fn pub_key(&self) -> PeerPublicKey {
@@ -568,6 +964,20 @@ impl RegisteredResponse for v4::response::RegisteredResponse {
 }

 impl RegisteredResponse for v5::response::RegisteredResponse {
+    fn private_ips(&self) -> IpPair {
+        self.reply.private_ips.into()
+    }
+
+    fn pub_key(&self) -> PeerPublicKey {
+        self.reply.pub_key
+    }
+
+    fn wg_port(&self) -> u16 {
+        self.reply.wg_port
+    }
+}
+
+impl RegisteredResponse for v6::response::RegisteredResponse {
    fn private_ips(&self) -> IpPair {
        self.reply.private_ips
    }
@@ -581,7 +991,7 @@ impl RegisteredResponse for v5::response::RegisteredResponse {
    }
 }

-pub trait RemainingBandwidthResponse: Id + fmt::Debug {
+pub trait RemainingBandwidthResponse: Id + UpgradeModeStatus + fmt::Debug {
    fn available_bandwidth(&self) -> Option<i64>;
 }

@@ -609,7 +1019,13 @@ impl RemainingBandwidthResponse for v5::response::RemainingBandwidthResponse {
    }
 }

-pub trait TopUpBandwidthResponse: Id + fmt::Debug {
+impl RemainingBandwidthResponse for v6::response::RemainingBandwidthResponse {
+    fn available_bandwidth(&self) -> Option<i64> {
+        self.reply.as_ref().map(|r| r.available_bandwidth)
+    }
+}
+
+pub trait TopUpBandwidthResponse: Id + UpgradeModeStatus + fmt::Debug {
    fn available_bandwidth(&self) -> i64;
 }

@@ -630,3 +1046,9 @@ impl TopUpBandwidthResponse for v5::response::TopUpBandwidthResponse {
        self.reply.available_bandwidth
    }
 }
+
+impl TopUpBandwidthResponse for v6::response::TopUpBandwidthResponse {
+    fn available_bandwidth(&self) -> i64 {
+        self.reply.available_bandwidth
+    }
+}
@@ -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,
@@ -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
@@ -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()
@@ -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)
@@ -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 },
+}
@@ -1,7 +1,7 @@
 // Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use super::{v1, v2, v3, v4, v5};
+use super::{v1, v2, v3, v4, v5, v6};
 use nym_service_provider_requests_common::{Protocol, ServiceProviderType};

 #[derive(Copy, Clone, Debug, PartialEq, strum_macros::Display)]
@@ -22,11 +22,15 @@ pub enum AuthenticatorVersion {
    /// 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::V5;
+    pub const LATEST: Self = Self::V6;

    pub const fn release_version(&self) -> semver::Version {
        match self {
@@ -35,6 +39,7 @@ impl AuthenticatorVersion {
            AuthenticatorVersion::V3 => semver::Version::new(1, 1, 10),
            AuthenticatorVersion::V4 => semver::Version::new(1, 2, 0),
            AuthenticatorVersion::V5 => semver::Version::new(1, 6, 1),
+            AuthenticatorVersion::V6 => semver::Version::new(1, 23, 0),
            AuthenticatorVersion::UNKNOWN => semver::Version::new(0, 0, 0),
        }
    }
@@ -54,6 +59,8 @@ impl From<Protocol> for AuthenticatorVersion {
            AuthenticatorVersion::V4
        } else if value.version == v5::VERSION {
            AuthenticatorVersion::V5
+        } else if value.version == v6::VERSION {
+            AuthenticatorVersion::V6
        } else {
            AuthenticatorVersion::UNKNOWN
        }
@@ -72,6 +79,8 @@ impl From<u8> for AuthenticatorVersion {
            AuthenticatorVersion::V4
        } else if value == v5::VERSION {
            AuthenticatorVersion::V5
+        } else if value == v6::VERSION {
+            AuthenticatorVersion::V6
        } else {
            AuthenticatorVersion::UNKNOWN
        }
@@ -126,11 +135,14 @@ impl From<semver::Version> for AuthenticatorVersion {
        if semver < AuthenticatorVersion::V5.release_version() {
            return Self::V4;
        }
-        // if provided version is higher (or equal) to release version of V5,
-        // we return the latest (i.e. v5)
+        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::V5,
+            Self::V6,
            Self::LATEST,
            "a new AuthenticatorVersion variant has been introduced without adjusting the `From<semver::Version>` trait"
        );
@@ -191,5 +203,9 @@ mod tests {
        assert_eq!(AuthenticatorVersion::V5, "1.7.0".into());
        assert_eq!(AuthenticatorVersion::V5, "1.16.11".into());
        assert_eq!(AuthenticatorVersion::V5, "1.17.0".into());
+        assert_eq!(AuthenticatorVersion::V5, "1.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,21 +7,16 @@ license.workspace = true
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

 [dependencies]
-async-trait = { workspace =  true }
-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::{
@@ -220,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>
@@ -11,6 +11,9 @@ use crate::{error::BandwidthControllerError, BandwidthController, PreparedCreden

 pub const DEFAULT_TICKETS_TO_SPEND: u32 = 1;

+// TODO: this does not really belong here
+pub const UPGRADE_MODE_JWT_TYPE: &str = "UPGRADE_MODE_JWT";
+
 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
 #[cfg_attr(not(target_arch = "wasm32"), async_trait)]
 pub trait BandwidthTicketProvider: Send + Sync {
@@ -20,6 +23,8 @@ pub trait BandwidthTicketProvider: Send + Sync {
        gateway_id: ed25519::PublicKey,
        tickets_to_spend: u32,
    ) -> Result<PreparedCredential, BandwidthControllerError>;
+
+    async fn get_upgrade_mode_token(&self) -> Result<Option<String>, BandwidthControllerError>;
 }

 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
@@ -39,4 +44,16 @@ where
        self.prepare_ecash_ticket(ticket_type, gateway_id.to_bytes(), tickets_to_spend)
            .await
    }
+
+    async fn get_upgrade_mode_token(&self) -> Result<Option<String>, BandwidthControllerError> {
+        let Some(emergency_credential) =
+            self.get_emergency_credential(UPGRADE_MODE_JWT_TYPE).await?
+        else {
+            return Ok(None);
+        };
+        // upgrade mode credential is just a simple stringified JWT
+        let token = String::from_utf8(emergency_credential.data.content)
+            .map_err(|_| BandwidthControllerError::MalformedUpgradeModeToken)?;
+        Ok(Some(token))
+    }
 }
@@ -81,6 +81,10 @@ pub struct CommonClientInitArgs {
    #[cfg_attr(feature = "cli", clap(long, hide = true))]
    pub enabled_credentials_mode: Option<bool>,

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

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

    #[error("no gateways on network")]
    NoGatewaysOnNetwork,
@@ -441,7 +441,7 @@ mod tests {

    #[test]
    fn test_multiple_urls_prepared_for_retries() {
-        let urls = vec![
+        let urls = [
            Url::parse("https://api1.nym.com").unwrap(),
            Url::parse("https://api2.nym.com").unwrap(),
            Url::parse("https://api3.nym.com").unwrap(),
@@ -30,7 +30,6 @@ pub(crate) async fn connect_async(
            resolver
                .resolve_str(domain)
                .await?
-                .into_iter()
                .map(|a| SocketAddr::new(a, port))
                .collect()
        }
@@ -88,3 +88,6 @@ features = ["js"]

 [features]
 wasm = []
+
+[lints]
+workspace = true
@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use si_scale::helpers::bibytes2;
+use std::fmt::{Display, Formatter};
 use std::sync::atomic::{AtomicBool, AtomicI64, Ordering};
 use std::sync::Arc;
 use std::time::Duration;
@@ -26,6 +27,39 @@ pub struct ClientBandwidth {
    inner: Arc<ClientBandwidthInner>,
 }

+// simple helper for logging purposes to accommodate 'unknown' case
+pub(crate) enum UpgradeModeEnabledWrapper {
+    True,
+    False,
+    Unknown,
+}
+
+impl From<Option<bool>> for UpgradeModeEnabledWrapper {
+    fn from(value: Option<bool>) -> Self {
+        match value {
+            Some(true) => UpgradeModeEnabledWrapper::True,
+            Some(false) => UpgradeModeEnabledWrapper::False,
+            None => UpgradeModeEnabledWrapper::Unknown,
+        }
+    }
+}
+
+impl From<bool> for UpgradeModeEnabledWrapper {
+    fn from(value: bool) -> Self {
+        Some(value).into()
+    }
+}
+
+impl Display for UpgradeModeEnabledWrapper {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            UpgradeModeEnabledWrapper::True => write!(f, "true"),
+            UpgradeModeEnabledWrapper::False => write!(f, "false"),
+            UpgradeModeEnabledWrapper::Unknown => write!(f, "unknown"),
+        }
+    }
+}
+
 struct ClientBandwidthInner {
    /// the actual bandwidth amount (in bytes) available
    available: AtomicI64,
@@ -71,26 +105,41 @@ impl ClientBandwidth {
        self.inner.available.load(Ordering::Acquire)
    }

-    pub(crate) fn maybe_log_bandwidth(&self, now: Option<OffsetDateTime>) {
+    pub(crate) fn maybe_log_bandwidth(
+        &self,
+        now: Option<OffsetDateTime>,
+        upgrade_mode: impl Into<UpgradeModeEnabledWrapper>,
+    ) {
        let last = self.last_logged();
        let now = now.unwrap_or_else(OffsetDateTime::now_utc);
        if last + Duration::from_secs(10) < now {
-            self.log_bandwidth(Some(now))
+            self.log_bandwidth(Some(now), upgrade_mode)
        }
    }

-    pub(crate) fn log_bandwidth(&self, now: Option<OffsetDateTime>) {
+    pub(crate) fn log_bandwidth(
+        &self,
+        now: Option<OffsetDateTime>,
+        upgrade_mode: impl Into<UpgradeModeEnabledWrapper>,
+    ) {
        let now = now.unwrap_or_else(OffsetDateTime::now_utc);
+        let upgrade_mode = upgrade_mode.into();

        let remaining = self.remaining();
        let remaining_bi2 = bibytes2(remaining as f64);

        if remaining < 0 {
-            tracing::warn!("OUT OF BANDWIDTH. remaining: {remaining_bi2}");
+            tracing::warn!(
+                "OUT OF BANDWIDTH. remaining: {remaining_bi2}. in 'upgrade mode': {upgrade_mode}"
+            );
        } else if remaining < 1_000_000 {
-            tracing::info!("remaining bandwidth: {remaining_bi2}");
+            tracing::info!(
+                "remaining bandwidth: {remaining_bi2}. in 'upgrade mode': {upgrade_mode}"
+            );
        } else {
-            tracing::debug!("remaining bandwidth: {remaining_bi2}");
+            tracing::trace!(
+                "remaining bandwidth: {remaining_bi2}. in 'upgrade mode': {upgrade_mode}"
+            );
        }

        self.inner
@@ -98,26 +147,35 @@ impl ClientBandwidth {
            .store(now.unix_timestamp(), Ordering::Relaxed)
    }

-    pub(crate) fn update_and_maybe_log(&self, remaining: i64) {
+    pub(crate) fn update_and_maybe_log(
+        &self,
+        remaining: i64,
+        upgrade_mode: impl Into<UpgradeModeEnabledWrapper>,
+    ) {
        let now = OffsetDateTime::now_utc();
        self.inner.available.store(remaining, Ordering::Release);
        self.inner
            .last_updated_ts
            .store(now.unix_timestamp(), Ordering::Relaxed);
-        self.maybe_log_bandwidth(Some(now))
+        self.maybe_log_bandwidth(Some(now), upgrade_mode)
    }

-    pub(crate) fn update_and_log(&self, remaining: i64) {
+    pub(crate) fn update_and_log(
+        &self,
+        remaining: i64,
+        upgrade_mode: impl Into<UpgradeModeEnabledWrapper>,
+    ) {
        let now = OffsetDateTime::now_utc();
        self.inner.available.store(remaining, Ordering::Release);
        self.inner
            .last_updated_ts
            .store(now.unix_timestamp(), Ordering::Relaxed);
-        self.log_bandwidth(Some(now))
+        self.log_bandwidth(Some(now), upgrade_mode)
    }

    fn last_logged(&self) -> OffsetDateTime {
        // SAFETY: this value is always populated with valid timestamps
+        #[allow(clippy::unwrap_used)]
        OffsetDateTime::from_unix_timestamp(self.inner.last_logged_ts.load(Ordering::Relaxed))
            .unwrap()
    }
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

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

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

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

    pub const DEFAULT_CUTOFF_REMAINING_BANDWIDTH_THRESHOLD: Option<i64> = None;

@@ -20,9 +20,9 @@ use nym_credentials_interface::TicketType;
 use nym_crypto::asymmetric::ed25519;
 use nym_gateway_requests::registration::handshake::client_handshake;
 use nym_gateway_requests::{
-    BinaryRequest, ClientControlRequest, ClientRequest, GatewayProtocolVersionExt,
-    GatewayRequestsError, SensitiveServerResponse, ServerResponse, SharedGatewayKey,
-    SharedSymmetricKey, CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION, CURRENT_PROTOCOL_VERSION,
+    BandwidthResponse, BinaryRequest, ClientControlRequest, ClientRequest, GatewayProtocolVersion,
+    GatewayProtocolVersionExt, GatewayRequestsError, SensitiveServerResponse, ServerResponse,
+    SharedGatewayKey, SharedSymmetricKey, CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION,
 };
 use nym_sphinx::forwarding::packet::MixPacket;
 use nym_statistics_common::clients::connection::ConnectionStatsEvent;
@@ -101,8 +101,7 @@ pub struct GatewayClient<C, St = EphemeralCredentialStorage> {
    bandwidth_controller: Option<BandwidthController<C, St>>,
    stats_reporter: ClientStatsSender,

-    // currently unused (but populated)
-    negotiated_protocol: Option<u8>,
+    negotiated_protocol: Option<GatewayProtocolVersion>,

    // Callback on the fd as soon as the connection has been established
    #[cfg(unix)]
@@ -166,10 +165,12 @@ impl<C, St> GatewayClient<C, St> {
    }

    #[cfg(not(target_arch = "wasm32"))]
+    #[allow(clippy::unreachable)]
    async fn _close_connection(&mut self) -> Result<(), GatewayClientError> {
        match std::mem::replace(&mut self.connection, SocketState::NotConnected) {
            SocketState::Available(mut socket) => Ok((*socket).close(None).await?),
            SocketState::PartiallyDelegated(_) => {
+                // SAFETY: this is only called after the caller has already recovered the connection
                unreachable!("this branch should have never been reached!")
            }
            _ => Ok(()), // no need to do anything in those cases
@@ -177,6 +178,7 @@ impl<C, St> GatewayClient<C, St> {
    }

    #[cfg(target_arch = "wasm32")]
+    #[allow(clippy::unreachable)]
    async fn _close_connection(&mut self) -> Result<(), GatewayClientError> {
        match std::mem::replace(&mut self.connection, SocketState::NotConnected) {
            SocketState::Available(socket) => {
@@ -184,6 +186,7 @@ impl<C, St> GatewayClient<C, St> {
                Ok(())
            }
            SocketState::PartiallyDelegated(_) => {
+                // SAFETY: this is only called after the caller has already recovered the connection
                unreachable!("this branch should have never been reached!")
            }
            _ => Ok(()), // no need to do anything in those cases
@@ -458,43 +461,16 @@ impl<C, St> GatewayClient<C, St> {
        }
    }

-    fn check_gateway_protocol(
-        &self,
-        gateway_protocol: Option<u8>,
-    ) -> Result<(), GatewayClientError> {
-        debug!("gateway protocol: {gateway_protocol:?}, ours: {CURRENT_PROTOCOL_VERSION}");
-
-        // right now there are no failure cases here, but this might change in the future
-        match gateway_protocol {
-            None => {
-                warn!("the gateway we're connected to has not specified its protocol version. It's probably running version < 1.1.X, but that's still fine for now. It will become a hard error in 1.2.0");
-                // note: in +1.2.0 we will have to return a hard error here
-                Ok(())
-            }
-            Some(v) if v > CURRENT_PROTOCOL_VERSION => {
-                let err = GatewayClientError::IncompatibleProtocol {
-                    gateway: Some(v),
-                    current: CURRENT_PROTOCOL_VERSION,
-                };
-                error!("{err}");
-                Err(err)
-            }
-
-            Some(_) => {
-                debug!("the gateway is using exactly the same (or older) protocol version as we are. We're good to continue!");
-                Ok(())
-            }
-        }
-    }
-
    async fn register(
        &mut self,
-        derive_aes256_gcm_siv_key: bool,
+        supported_gateway_protocol: Option<GatewayProtocolVersion>,
    ) -> Result<(), GatewayClientError> {
        if !self.connection.is_established() {
            return Err(GatewayClientError::ConnectionNotEstablished);
        }

+        let derive_aes256_gcm_siv_key = supported_gateway_protocol.supports_aes256_gcm_siv();
+
        debug_assert!(self.connection.is_available());
        log::debug!(
            "registering with gateway. using legacy key derivation: {}",
@@ -505,14 +481,13 @@ impl<C, St> GatewayClient<C, St> {
        // and putting it into the GatewayClient struct would be a hassle
        let mut rng = OsRng;

-        let shared_key = match &mut self.connection {
+        let handshake_result = match &mut self.connection {
            SocketState::Available(ws_stream) => client_handshake(
                &mut rng,
                ws_stream,
                self.local_identity.as_ref(),
                self.gateway_identity,
-                self.cfg.bandwidth.require_tickets,
-                derive_aes256_gcm_siv_key,
+                supported_gateway_protocol,
                #[cfg(not(target_arch = "wasm32"))]
                self.shutdown_token.clone(),
            )
@@ -521,26 +496,31 @@ impl<C, St> GatewayClient<C, St> {
            _ => return Err(GatewayClientError::ConnectionInInvalidState),
        }?;

-        let (authentication_status, gateway_protocol) = match self.read_control_response().await? {
+        let authentication_status = match self.read_control_response().await? {
            ServerResponse::Register {
-                protocol_version,
                status,
-            } => (status, protocol_version),
+                upgrade_mode,
+                ..
+            } => {
+                if upgrade_mode {
+                    warn!("the system is currently undergoing an upgrade. some of its functionalities might be unstable")
+                }
+                status
+            }
            ServerResponse::Error { message } => {
                return Err(GatewayClientError::GatewayError(message))
            }
            other => return Err(GatewayClientError::UnexpectedResponse { name: other.name() }),
        };

-        self.check_gateway_protocol(gateway_protocol)?;
        self.authenticated = authentication_status;

        if self.authenticated {
-            self.shared_key = Some(Arc::new(shared_key));
+            self.shared_key = Some(Arc::new(handshake_result.derived_key));
        }

        // populate the negotiated protocol for future uses
-        self.negotiated_protocol = gateway_protocol;
+        self.negotiated_protocol = Some(handshake_result.negotiated_protocol);

        Ok(())
    }
@@ -623,13 +603,24 @@ impl<C, St> GatewayClient<C, St> {
                protocol_version,
                status,
                bandwidth_remaining,
+                upgrade_mode,
            } => {
-                self.check_gateway_protocol(protocol_version)?;
+                if protocol_version.is_future_version() {
+                    // SAFETY: future version is always defined
+                    #[allow(clippy::unwrap_used)]
+                    let version = protocol_version.unwrap();
+                    error!("the gateway insists on using v{version} protocol which is not supported by this client");
+                    return Err(GatewayClientError::AuthenticationFailure);
+                }
                self.authenticated = status;
-                self.bandwidth.update_and_maybe_log(bandwidth_remaining);
+                self.bandwidth
+                    .update_and_maybe_log(bandwidth_remaining, upgrade_mode);

                self.negotiated_protocol = protocol_version;
                log::debug!("authenticated: {status}, bandwidth remaining: {bandwidth_remaining}");
+                if upgrade_mode {
+                    warn!("the system is currently undergoing an upgrade. some of its functionalities might be unstable")
+                }

                Ok(())
            }
@@ -650,7 +641,7 @@ impl<C, St> GatewayClient<C, St> {
            .public_key()
            .derive_destination_address();

-        let msg = ClientControlRequest::new_authenticate(
+        let msg = ClientControlRequest::new_legacy_authenticate(
            self_address,
            shared_key,
            self.cfg.bandwidth.require_tickets,
@@ -659,25 +650,40 @@ impl<C, St> GatewayClient<C, St> {
            .await
    }

-    async fn authenticate_v2(&mut self) -> Result<(), GatewayClientError> {
+    async fn authenticate_v2(
+        &mut self,
+        requested_protocol_version: GatewayProtocolVersion,
+    ) -> Result<(), GatewayClientError> {
        debug!("using v2 authentication");
        let Some(shared_key) = self.shared_key.as_ref() else {
            return Err(GatewayClientError::NoSharedKeyAvailable);
        };

-        let msg = ClientControlRequest::new_authenticate_v2(shared_key, &self.local_identity)?;
+        let msg = ClientControlRequest::new_authenticate_v2(
+            shared_key,
+            &self.local_identity,
+            requested_protocol_version,
+        )?;
        self.send_authenticate_request_and_handle_response(msg)
            .await
    }

-    async fn authenticate(&mut self, use_v2: bool) -> Result<(), GatewayClientError> {
+    async fn authenticate(
+        &mut self,
+        supported_gateway_protocol: Option<GatewayProtocolVersion>,
+    ) -> Result<(), GatewayClientError> {
        if !self.connection.is_established() {
            return Err(GatewayClientError::ConnectionNotEstablished);
        }
        debug!("authenticating with gateway");

-        if use_v2 {
-            self.authenticate_v2().await
+        if supported_gateway_protocol.supports_authenticate_v2() {
+            // use the highest possible protocol version the gateway has announced support for
+
+            // SAFETY: if announced protocol supports auth v2, it means it's properly set
+            #[allow(clippy::unwrap_used)]
+            self.authenticate_v2(supported_gateway_protocol.unwrap())
+                .await
        } else {
            self.authenticate_v1().await
        }
@@ -708,9 +714,12 @@ impl<C, St> GatewayClient<C, St> {
            }
        };

+        debug!("supported gateway protocol: {gw_protocol:?}");
+
        let supports_aes_gcm_siv = gw_protocol.supports_aes256_gcm_siv();
        let supports_auth_v2 = gw_protocol.supports_authenticate_v2();
        let supports_key_rotation_info = gw_protocol.supports_key_rotation_packet();
+        let supports_upgrade_mode = gw_protocol.supports_upgrade_mode();

        if !supports_aes_gcm_siv {
            warn!("this gateway is on an old version that doesn't support AES256-GCM-SIV");
@@ -721,6 +730,16 @@ impl<C, St> GatewayClient<C, St> {
        if !supports_key_rotation_info {
            warn!("this gateway is on an old version that doesn't support key rotation packets")
        }
+        if !supports_upgrade_mode {
+            warn!("this gateway is on an old version that doesn't support upgrade mode")
+        }
+
+        let gw_protocol = if gw_protocol.is_future_version() {
+            warn!("we're running outdated software as gateway is announcing protocol {gw_protocol:?} whilst we're using {}. we're going to attempt to downgrade", GatewayProtocolVersion::CURRENT);
+            Some(GatewayProtocolVersion::CURRENT)
+        } else {
+            gw_protocol
+        };

        if self.authenticated {
            debug!("Already authenticated");
@@ -735,10 +754,11 @@ impl<C, St> GatewayClient<C, St> {
        }

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

            if self.authenticated {
                // if we are authenticated it means we MUST have an associated shared_key
+                #[allow(clippy::unwrap_used)]
                let shared_key = self.shared_key.as_ref().unwrap();

                let requires_key_upgrade = shared_key.is_legacy() && supports_aes_gcm_siv;
@@ -751,9 +771,10 @@ impl<C, St> GatewayClient<C, St> {
                Err(GatewayClientError::AuthenticationFailure)
            }
        } else {
-            self.register(supports_aes_gcm_siv).await?;
+            self.register(gw_protocol).await?;

            // if registration didn't return an error, we MUST have an associated shared key
+            #[allow(clippy::unwrap_used)]
            let shared_key = self.shared_key.as_ref().unwrap();

            // we're always registering with the highest supported protocol,
@@ -783,51 +804,81 @@ impl<C, St> GatewayClient<C, St> {
        }
    }

-    async fn claim_ecash_bandwidth(
+    async fn wait_for_bandwidth_response(
        &mut self,
-        credential: CredentialSpendingData,
-    ) -> Result<(), GatewayClientError> {
-        let msg = ClientControlRequest::new_enc_ecash_credential(
-            credential,
-            self.shared_key.as_ref().unwrap(),
-        )?;
-        let bandwidth_remaining = match self
+        msg: ClientControlRequest,
+    ) -> Result<BandwidthResponse, GatewayClientError> {
+        let response = match self
            .send_websocket_message_with_non_send_response(msg)
            .await?
        {
-            ServerResponse::Bandwidth { available_total } => Ok(available_total),
+            ServerResponse::Bandwidth(response) => {
+                if response.upgrade_mode {
+                    info!("the system is currently undergoing an upgrade. our bandwidth shouldn't have been metered")
+                }
+                Ok(response)
+            }
            ServerResponse::Error { message } => Err(GatewayClientError::GatewayError(message)),
            ServerResponse::TypedError { error } => {
                Err(GatewayClientError::TypedGatewayError(error))
            }
            other => Err(GatewayClientError::UnexpectedResponse { name: other.name() }),
        }?;
+        Ok(response)
+    }
+
+    async fn claim_ecash_bandwidth(
+        &mut self,
+        credential: CredentialSpendingData,
+    ) -> Result<(), GatewayClientError> {
+        // SAFETY: claiming ecash bandwidth is called as part of `claim_bandwidth` which
+        // ensures the shared key is defined
+        #[allow(clippy::unwrap_used)]
+        let msg = ClientControlRequest::new_enc_ecash_credential(
+            credential,
+            self.shared_key.as_ref().unwrap(),
+        )?;
+        let response = self.wait_for_bandwidth_response(msg).await?;

        // TODO: create tracing span
        info!("managed to claim ecash bandwidth");
-        self.bandwidth.update_and_log(bandwidth_remaining);
+        self.bandwidth
+            .update_and_log(response.available_total, response.upgrade_mode);
+
+        Ok(())
+    }
+
+    pub async fn send_upgrade_mode_jwt(&mut self, token: String) -> Result<(), GatewayClientError> {
+        let msg = ClientControlRequest::new_upgrade_mode_jwt(token);
+        let response = self.wait_for_bandwidth_response(msg).await?;
+
+        // if gateway rejected our jwt, we would have returned an error
+        info!("gateway has accepted our jwt");
+        if !response.upgrade_mode {
+            error!("but we're not in upgrade mode - something is wrong!");
+            return Err(GatewayClientError::UnexpectedUpgradeModeState);
+        }
+
+        self.bandwidth
+            .update_and_log(response.available_total, response.upgrade_mode);

        Ok(())
    }

    async fn try_claim_testnet_bandwidth(&mut self) -> Result<(), GatewayClientError> {
        let msg = ClientControlRequest::ClaimFreeTestnetBandwidth;
-        let bandwidth_remaining = match self
-            .send_websocket_message_with_non_send_response(msg)
-            .await?
-        {
-            ServerResponse::Bandwidth { available_total } => Ok(available_total),
-            ServerResponse::Error { message } => Err(GatewayClientError::GatewayError(message)),
-            other => Err(GatewayClientError::UnexpectedResponse { name: other.name() }),
-        }?;
+        let response = self.wait_for_bandwidth_response(msg).await?;

        info!("managed to claim testnet bandwidth");
-        self.bandwidth.update_and_log(bandwidth_remaining);
+        self.bandwidth
+            .update_and_log(response.available_total, response.upgrade_mode);

        Ok(())
    }

    fn unchecked_bandwidth_controller(&self) -> &BandwidthController<C, St> {
+        // this is an unchecked method
+        #[allow(clippy::unwrap_used)]
        self.bandwidth_controller.as_ref().unwrap()
    }

@@ -919,6 +970,7 @@ impl<C, St> GatewayClient<C, St> {
            BinaryRequest::ForwardSphinx { packet }
        };

+        #[allow(clippy::expect_used)]
        req.into_ws_message(
            self.shared_key
                .as_ref()
@@ -1025,6 +1077,8 @@ impl<C, St> GatewayClient<C, St> {
        self.send_with_reconnection_on_failure(msg).await
    }

+    // SAFETY: this method is only called when the connection is in `PartiallyDelegated` state
+    #[allow(clippy::unreachable)]
    async fn recover_socket_connection(&mut self) -> Result<(), GatewayClientError> {
        if self.connection.is_available() {
            return Ok(());
@@ -1054,6 +1108,7 @@ impl<C, St> GatewayClient<C, St> {
            return Err(GatewayClientError::ConnectionInInvalidState);
        }

+        #[allow(clippy::expect_used)]
        let partially_delegated =
            match std::mem::replace(&mut self.connection, SocketState::Invalid) {
                SocketState::Available(conn) => {
@@ -1069,7 +1124,13 @@ impl<C, St> GatewayClient<C, St> {
                        self.shutdown_token.clone(),
                    )
                }
-                _ => unreachable!(),
+                other => {
+                    error!(
+                        "attempted to start mixnet listener whilst the connection is in {} state!",
+                        other.name()
+                    );
+                    return Err(GatewayClientError::ConnectionInInvalidState);
+                }
            };

        self.connection = SocketState::PartiallyDelegated(partially_delegated);
@@ -1082,8 +1143,7 @@ impl<C, St> GatewayClient<C, St> {
        }

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

        // this call is NON-blocking
        self.start_listening_for_mixnet_messages()?;
@@ -39,7 +39,6 @@ pub(crate) async fn connect_async(
            resolver
                .resolve_str(domain)
                .await?
-                .into_iter()
                .map(|a| SocketAddr::new(a, port))
                .collect()
        }
@@ -54,7 +54,7 @@ pub enum GatewayClientError {

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

    #[error("No shared key was provided or obtained")]
    NoSharedKeyAvailable,
@@ -128,6 +128,9 @@ pub enum GatewayClientError {
        "this operation couldn't be completed as the program is in the process of shutting down"
    )]
    ShutdownInProgress,
+
+    #[error("the system is an unexpected upgrade mode state")]
+    UnexpectedUpgradeModeState,
 }

 impl From<WsError> for GatewayClientError {
@@ -35,6 +35,7 @@ impl PacketRouter {
        }
    }

+    #[allow(clippy::panic)]
    pub fn route_mixnet_messages(
        &self,
        received_messages: Vec<Vec<u8>>,
@@ -54,6 +55,7 @@ impl PacketRouter {
        Ok(())
    }

+    #[allow(clippy::panic)]
    pub fn route_acks(&self, received_acks: Vec<Vec<u8>>) -> Result<(), GatewayClientError> {
        if let Err(err) = self.ack_sender.unbounded_send(received_acks) {
            // check if the failure is due to the shutdown being in progress and thus the receiver channel
@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::bandwidth::ClientBandwidth;
+use crate::client::config::BandwidthTickets;
 use crate::error::GatewayClientError;
 use crate::packet_router::PacketRouter;
 use crate::traits::GatewayPacketRouter;
@@ -10,7 +11,9 @@ use futures::channel::oneshot;
 use futures::stream::{SplitSink, SplitStream};
 use futures::{SinkExt, StreamExt};
 use nym_gateway_requests::shared_key::SharedGatewayKey;
-use nym_gateway_requests::{SensitiveServerResponse, ServerResponse, SimpleGatewayRequestsError};
+use nym_gateway_requests::{
+    SendResponse, SensitiveServerResponse, ServerResponse, SimpleGatewayRequestsError,
+};
 use nym_task::ShutdownToken;
 use si_scale::helpers::bibytes2;
 use std::os::raw::c_int as RawFd;
@@ -154,11 +157,12 @@ impl PartiallyDelegatedRouter {
    fn handle_text_message(&self, text: String) -> Result<(), GatewayClientError> {
        // if we fail to deserialise the response, return a hard error. we can't handle garbage
        match ServerResponse::try_from(text).map_err(|_| GatewayClientError::MalformedResponse)? {
-            ServerResponse::Send {
+            ServerResponse::Send(SendResponse {
                remaining_bandwidth,
-            } => {
+                upgrade_mode,
+            }) => {
                self.client_bandwidth
-                    .update_and_maybe_log(remaining_bandwidth);
+                    .update_and_maybe_log(remaining_bandwidth, upgrade_mode);
                Ok(())
            }
            ServerResponse::Error { message } => {
@@ -174,7 +178,20 @@ impl PartiallyDelegatedRouter {
                        let available_bi2 = bibytes2(available as f64);
                        let required_bi2 = bibytes2(required as f64);
                        warn!("run out of bandwidth when attempting to send the message! we got {available_bi2} available, but needed at least {required_bi2} to send the previous message");
-                        self.client_bandwidth.update_and_log(available);
+                        // if we run out of bandwidth (and tried to send reasonable amount of data),
+                        // the upgrade mode is implicitly disabled, as otherwise we would have been
+                        // to proceed
+                        let upgrade_mode = if available
+                            < BandwidthTickets::DEFAULT_REMAINING_BANDWIDTH_THRESHOLD
+                        {
+                            Some(false)
+                        } else {
+                            // we were attempting to send a lot of data at once
+                            // - we have no certainty about upgrade mode at this point
+                            None
+                        };
+                        self.client_bandwidth
+                            .update_and_log(available, upgrade_mode);
                        // UNIMPLEMENTED: we should stop sending messages until we recover bandwidth
                        Ok(())
                    }
@@ -327,6 +344,7 @@ impl PartiallyDelegatedHandle {
        Ok(self.sink_half.send_all(&mut send_stream).await?)
    }

+    #[allow(clippy::panic)]
    pub(crate) async fn merge(self) -> Result<WsConn, GatewayClientError> {
        let (mut stream_receiver, notify) = self.delegated_stream;

@@ -355,8 +373,10 @@ impl PartiallyDelegatedHandle {
            // in receive_res
            .map_err(|_| GatewayClientError::ConnectionAbruptlyClosed)?;
        let stream = stream_results?;
+
        // the error is thrown when trying to reunite sink and stream that did not originate
        // from the same split which is impossible to happen here
+        #[allow(clippy::unwrap_used)]
        Ok(self.sink_half.reunite(stream).unwrap())
    }
 }
@@ -387,4 +407,13 @@ impl SocketState {
            SocketState::Available(_) | SocketState::PartiallyDelegated(_)
        )
    }
+
+    pub(crate) fn name(&self) -> &'static str {
+        match self {
+            SocketState::Available(_) => "available",
+            SocketState::PartiallyDelegated(_) => "partially delegated",
+            SocketState::NotConnected => "not connected",
+            SocketState::Invalid => "invalid",
+        }
+    }
 }
@@ -27,6 +27,9 @@ pub struct Args {
    #[clap(long)]
    pub identity_key: String,

+    #[clap(long, help = "LP (Lewes Protocol) listener port (default: 41264)")]
+    pub lp_port: Option<u16>,
+
    #[clap(long)]
    pub profit_margin_percent: Option<u64>,

@@ -57,10 +60,13 @@ pub async fn bond_nymnode(args: Args, client: SigningClient) {
        return;
    }

+    let lp_address = args.lp_port.map(|port| format!("{}:{}", args.host, port));
+
    let nymnode = nym_mixnet_contract_common::NymNode {
        host: args.host,
        custom_http_port: args.http_api_port,
        identity_key: args.identity_key,
+        lp_address,
    };

    let coin = Coin::new(args.amount, denom);
@@ -25,6 +25,9 @@ pub struct Args {
    #[clap(long)]
    pub custom_http_api_port: Option<u16>,

+    #[clap(long, help = "LP (Lewes Protocol) listener port (default: 41264)")]
+    pub lp_port: Option<u16>,
+
    #[clap(long)]
    pub profit_margin_percent: Option<u64>,

@@ -47,10 +50,13 @@ pub struct Args {
 pub async fn create_payload(args: Args, client: SigningClient) {
    let denom = client.current_chain_details().mix_denom.base.as_str();

+    let lp_address = args.lp_port.map(|port| format!("{}:{}", args.host, port));
+
    let mixnode = nym_mixnet_contract_common::NymNode {
        host: args.host,
        custom_http_port: args.custom_http_api_port,
        identity_key: args.identity_key,
+        lp_address,
    };

    let coin = Coin::new(args.amount, denom);
@@ -19,6 +19,16 @@ pub struct Args {
    // equivalent to setting `custom_http_port` to `None`
    #[clap(long)]
    pub restore_default_http_port: bool,
+
+    #[clap(
+        long,
+        help = "LP (Lewes Protocol) listener address (format: host:port)"
+    )]
+    pub lp_address: Option<String>,
+
+    // equivalent to setting `lp_address` to `None`
+    #[clap(long)]
+    pub restore_default_lp_address: bool,
 }

 pub async fn update_config(args: Args, client: SigningClient) {
@@ -39,6 +49,8 @@ pub async fn update_config(args: Args, client: SigningClient) {
        host: args.host,
        custom_http_port: args.custom_http_port,
        restore_default_http_port: args.restore_default_http_port,
+        lp_address: args.lp_address,
+        restore_default_lp_address: args.restore_default_lp_address,
    };

    let res = client
@@ -241,23 +241,28 @@ impl Epoch {
 //
 // Note: It's important that the variant ordering is not changed otherwise it would mess up the derived `PartialOrd`
 #[cw_serde]
-#[derive(Copy)]
+#[derive(Copy, Default)]
 pub enum EpochState {
+    #[default]
    WaitingInitialisation,
-    PublicKeySubmission { resharing: bool },
-    DealingExchange { resharing: bool },
-    VerificationKeySubmission { resharing: bool },
-    VerificationKeyValidation { resharing: bool },
-    VerificationKeyFinalization { resharing: bool },
+    PublicKeySubmission {
+        resharing: bool,
+    },
+    DealingExchange {
+        resharing: bool,
+    },
+    VerificationKeySubmission {
+        resharing: bool,
+    },
+    VerificationKeyValidation {
+        resharing: bool,
+    },
+    VerificationKeyFinalization {
+        resharing: bool,
+    },
    InProgress,
 }

-impl Default for EpochState {
-    fn default() -> Self {
-        Self::WaitingInitialisation
-    }
-}
-
 impl Display for EpochState {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
@@ -1,3 +1,7 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.

-export type NodeConfigUpdate = { host: string | null, custom_http_port: number | null, restore_default_http_port: boolean, };
+export type NodeConfigUpdate = { host: string | null, custom_http_port: number | null, restore_default_http_port: boolean, 
+/**
+ * LP listener address for direct gateway connections (format: "host:port")
+ */
+lp_address: string | null, restore_default_lp_address: boolean, };
@@ -17,4 +17,9 @@ custom_http_port: number | null,
 /**
 * Base58-encoded ed25519 EdDSA public key.
 */
-identity_key: string, };
+identity_key: string, 
+/**
+ * Optional LP (Lewes Protocol) listener address for direct gateway connections.
+ * Format: "host:port", for example "1.1.1.1:41264" or "gateway.example.com:41264"
+ */
+lp_address: string | null, };
@@ -373,6 +373,11 @@ pub struct NymNode {
    /// Base58-encoded ed25519 EdDSA public key.
    #[cfg_attr(feature = "utoipa", schema(value_type = String))]
    pub identity_key: IdentityKey,
+
+    /// Optional LP (Lewes Protocol) listener address for direct gateway connections.
+    /// Format: "host:port", for example "1.1.1.1:41264" or "gateway.example.com:41264"
+    #[serde(default)]
+    pub lp_address: Option<String>,
    // TODO: I don't think we want to include sphinx keys here,
    // given we want to rotate them and keeping that in sync with contract will be a PITA
 }
@@ -405,6 +410,7 @@ impl From<MixNode> for NymNode {
            host: value.host,
            custom_http_port: Some(value.http_api_port),
            identity_key: value.identity_key,
+            lp_address: None,
        }
    }
 }
@@ -415,6 +421,7 @@ impl From<Gateway> for NymNode {
            host: value.host,
            custom_http_port: None,
            identity_key: value.identity_key,
+            lp_address: None,
        }
    }
 }
@@ -437,6 +444,13 @@ pub struct NodeConfigUpdate {
    // equivalent to setting `custom_http_port` to `None`
    #[serde(default)]
    pub restore_default_http_port: bool,
+
+    /// LP listener address for direct gateway connections (format: "host:port")
+    pub lp_address: Option<String>,
+
+    // equivalent to setting `lp_address` to `None`
+    #[serde(default)]
+    pub restore_default_lp_address: bool,
 }

 #[cw_serde]
@@ -8,7 +8,7 @@ async fn main() -> anyhow::Result<()> {
    use sqlx::{Connection, SqliteConnection};
    use std::env;

-    let out_dir = env::var("OUT_DIR")?;
+    let out_dir = env::var("OUT_DIR").context("missing OUT_DIR env variable")?;
    let database_path = format!("{out_dir}/nym-credential-proxy-example.sqlite");

    // remove the db file if it already existed from previous build
@@ -1,6 +1,7 @@
 // Copyright 2025 Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: GPL-3.0-only

+use nym_crypto::asymmetric::ed25519;
 use nym_ecash_signer_check::SignerCheckError;
 use nym_validator_client::coconut::EcashApiError;
 use nym_validator_client::nym_api::{EpochId, error::NymAPIError};
@@ -127,6 +128,13 @@ pub enum CredentialProxyError {
    #[error("failed to create deposit")]
    DepositFailure,

+    #[error("failed to load jwt signing key from {path}: {err}")]
+    JWTSigningKeyLoadFailure {
+        path: String,
+        #[source]
+        err: std::io::Error,
+    },
+
    #[error("can't obtain sufficient number of credential shares due to unavailable quorum")]
    UnavailableSigningQuorum,

@@ -161,6 +169,24 @@ pub enum CredentialProxyError {
        device_id: String,
        credential_id: String,
    },
+
+    #[error(
+        "the attestation check url has not been provided through either the CLI nor the default .env config"
+    )]
+    AttestationCheckUrlNotSet,
+
+    #[error("the provided attester public key is malformed: {source}")]
+    MalformedAttestationCheckUrl { source: url::ParseError },
+
+    #[error(
+        "the attester public key has not been provided through either the CLI nor the default .env config"
+    )]
+    AttesterPublicKeyNotSet,
+
+    #[error("the provided attester public key is malformed: {source}")]
+    MalformedAttesterPublicKey {
+        source: ed25519::Ed25519RecoveryError,
+    },
 }

 impl From<NymAPIError> for CredentialProxyError {
@@ -7,9 +7,9 @@ use crate::ticketbook_manager::TicketbookManager;
 use nym_compact_ecash::Base58;
 use nym_credential_proxy_requests::api::v1::ticketbook::models::{
    CurrentEpochResponse, DepositResponse, GlobalDataParams, MasterVerificationKeyResponse,
-    PartialVerificationKey, PartialVerificationKeysResponse, TicketbookAsyncRequest,
-    TicketbookObtainParams, TicketbookRequest, TicketbookWalletSharesAsyncResponse,
-    TicketbookWalletSharesResponse,
+    ObtainTicketBookSharesAsyncResponse, PartialVerificationKey, PartialVerificationKeysResponse,
+    TicketbookAsyncRequest, TicketbookObtainParams, TicketbookRequest,
+    TicketbookWalletSharesAsyncResponse, TicketbookWalletSharesResponse,
 };
 use time::OffsetDateTime;
 use tracing::{Instrument, Level, error, info, span, warn};
@@ -65,7 +65,7 @@ impl TicketbookManager {
        uuid: Uuid,
        request: TicketbookAsyncRequest,
        params: TicketbookObtainParams,
-    ) -> Result<TicketbookWalletSharesAsyncResponse, CredentialProxyError> {
+    ) -> Result<ObtainTicketBookSharesAsyncResponse, CredentialProxyError> {
        let requested_on = OffsetDateTime::now_utc();
        let span = span!(Level::INFO, "[async] obtain ticketboook", uuid = %uuid);
        async move {
@@ -110,7 +110,7 @@ impl TicketbookManager {
            }

            // 4. in the meantime, return the id to the user
-            Ok(TicketbookWalletSharesAsyncResponse { id, uuid })
+            Ok(TicketbookWalletSharesAsyncResponse { id, uuid }.into())
        }
        .instrument(span)
        .await
@@ -14,6 +14,7 @@ bincode = { workspace = true, optional = true }
 log = { workspace = true }
 thiserror = { workspace = true }
 serde = { workspace = true, features = ["derive"], optional = true }
+time = { workspace = true }
 tokio = { workspace = true, features = ["sync"] }
 zeroize = { workspace = true, features = ["zeroize_derive"] }

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+CREATE TABLE emergency_credential
+(
+    id         INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+    type       TEXT    NOT NULL,
+    -- don't define any strict schema on the content as it might be implementation-dependant
+    content    BLOB    NOT NULL,
+    expiration TIMESTAMP WITHOUT TIME ZONE
+);
+
+-- no point in allowing duplicate data
+CREATE UNIQUE INDEX emergency_credential_unique_type_content
+    ON emergency_credential (type, content);
@@ -1,7 +1,10 @@
 // Copyright 2023-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

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

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

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

        #[allow(clippy::unwrap_used)]
        let mut nasty_clone = hack_clone_ticketbook(ticketbook);
@@ -277,4 +295,41 @@ impl MemoryEcachTicketbookManager {
            sigs.signatures.clone(),
        );
    }
+
+    pub(crate) async fn get_emergency_credential(&self, typ: &str) -> Option<EmergencyCredential> {
+        let guard = self.inner.read().await;
+
+        guard.emergency_credentials.get(typ)?.first().cloned()
+    }
+
+    pub(crate) async fn insert_emergency_credential(
+        &self,
+        credential: &EmergencyCredentialContent,
+    ) {
+        let mut guard = self.inner.write().await;
+        let id = guard.next_emergency_credential_id();
+
+        guard
+            .emergency_credentials
+            .entry(credential.typ.clone())
+            .or_default()
+            .push(EmergencyCredential {
+                id,
+                data: credential.clone(),
+            });
+    }
+
+    pub(crate) async fn remove_emergency_credential(&self, id: i64) {
+        let mut guard = self.inner.write().await;
+
+        guard.emergency_credentials.retain(|_, credentials| {
+            credentials.retain(|c| c.id != id);
+            !credentials.is_empty()
+        })
+    }
+
+    pub(crate) async fn remove_emergency_credentials_of_type(&self, typ: &str) {
+        let mut guard = self.inner.write().await;
+        guard.emergency_credentials.remove(typ);
+    }
 }
@@ -2,8 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::models::{
-    BasicTicketbookInformation, RawCoinIndexSignatures, RawExpirationDateSignatures,
-    RawVerificationKey, StoredIssuedTicketbook, StoredPendingTicketbook,
+    BasicTicketbookInformation, EmergencyCredential, EmergencyCredentialContent,
+    RawCoinIndexSignatures, RawExpirationDateSignatures, RawVerificationKey,
+    StoredIssuedTicketbook, StoredPendingTicketbook,
 };
 use nym_ecash_time::Date;
 use sqlx::{Executor, Sqlite, Transaction};
@@ -305,6 +306,74 @@ impl SqliteEcashTicketbookManager {
            .await?;
        Ok(())
    }
+
+    pub(crate) async fn get_emergency_credential(
+        &self,
+        typ: &str,
+    ) -> Result<Option<EmergencyCredential>, sqlx::Error> {
+        sqlx::query_as(
+            r#"
+                SELECT *
+                FROM emergency_credential
+                WHERE type = ?
+                  AND (expiration IS NULL OR expiration > CURRENT_TIMESTAMP)
+                ORDER BY expiration DESC NULLS LAST
+                LIMIT 1
+            "#,
+        )
+        .bind(typ)
+        .fetch_optional(&*self.connection_pool)
+        .await
+    }
+
+    pub(crate) async fn insert_emergency_credential(
+        &self,
+        credential: &EmergencyCredentialContent,
+    ) -> Result<(), sqlx::Error> {
+        sqlx::query!(
+            r#"
+                INSERT INTO emergency_credential
+                (type, content, expiration)
+                VALUES (?, ?, ?)
+                ON CONFLICT(type, content) DO NOTHING;
+            "#,
+            credential.typ,
+            credential.content,
+            credential.expiration,
+        )
+        .execute(&*self.connection_pool)
+        .await?;
+        Ok(())
+    }
+
+    pub(crate) async fn remove_emergency_credential(&self, id: i64) -> Result<(), sqlx::Error> {
+        sqlx::query!(
+            r#"
+                DELETE FROM emergency_credential
+                WHERE id = ?
+            "#,
+            id
+        )
+        .execute(&*self.connection_pool)
+        .await?;
+        Ok(())
+    }
+
+    pub(crate) async fn remove_emergency_credentials_of_type(
+        &self,
+        typ: &str,
+    ) -> Result<(), sqlx::Error> {
+        sqlx::query!(
+            r#"
+                DELETE FROM emergency_credential
+                WHERE type = ?
+            "#,
+            typ
+        )
+        .execute(&*self.connection_pool)
+        .await?;
+        Ok(())
+    }
 }

 pub(crate) async fn get_next_unspent_ticketbook<'a, E>(
@@ -3,7 +3,10 @@

 use crate::backends::memory::MemoryEcachTicketbookManager;
 use crate::error::StorageError;
-use crate::models::{BasicTicketbookInformation, RetrievedPendingTicketbook, RetrievedTicketbook};
+use crate::models::{
+    BasicTicketbookInformation, EmergencyCredential, EmergencyCredentialContent,
+    RetrievedPendingTicketbook, RetrievedTicketbook,
+};
 use crate::storage::Storage;
 use async_trait::async_trait;
 use nym_compact_ecash::scheme::coin_indices_signatures::AnnotatedCoinIndexSignature;
@@ -218,6 +221,38 @@ impl Storage for EphemeralStorage {
            .await;
        Ok(())
    }
+
+    async fn get_emergency_credential(
+        &self,
+        typ: &str,
+    ) -> Result<Option<EmergencyCredential>, Self::StorageError> {
+        Ok(self.storage_manager.get_emergency_credential(typ).await)
+    }
+
+    async fn insert_emergency_credential(
+        &self,
+        credential: &EmergencyCredentialContent,
+    ) -> Result<(), Self::StorageError> {
+        self.storage_manager
+            .insert_emergency_credential(credential)
+            .await;
+        Ok(())
+    }
+
+    async fn remove_emergency_credential(&self, id: i64) -> Result<(), Self::StorageError> {
+        self.storage_manager.remove_emergency_credential(id).await;
+        Ok(())
+    }
+
+    async fn remove_emergency_credentials_of_type(
+        &self,
+        typ: &str,
+    ) -> Result<(), Self::StorageError> {
+        self.storage_manager
+            .remove_emergency_credentials_of_type(typ)
+            .await;
+        Ok(())
+    }
 }

 #[cfg(test)]
@@ -246,7 +281,7 @@ mod tests {
        let _exp_date_sigs = generate_expiration_date_signatures(
            sig_req.expiration_date.ecash_unix_timestamp(),
            &[signing_keys.secret_key()],
-            &vec![signing_keys.verification_key()],
+            &[signing_keys.verification_key()],
            &signing_keys.verification_key(),
            &[1],
        )?;
@@ -263,7 +298,7 @@ mod tests {

        let wallet = issuance.aggregate_signature_shares(
            &signing_keys.verification_key(),
-            &vec![partial_wallet],
+            &[partial_wallet],
            sig_req,
        )?;

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

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

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

 mod legacy_helpers;

+use crate::models::{EmergencyCredential, EmergencyCredentialContent};
 use crate::{
    backends::sqlite::{
        get_next_unspent_ticketbook, increase_used_ticketbook_tickets, SqliteEcashTicketbookManager,
@@ -401,4 +402,36 @@ impl Storage for PersistentStorage {
            .await?;
        Ok(())
    }
+
+    async fn get_emergency_credential(
+        &self,
+        typ: &str,
+    ) -> Result<Option<EmergencyCredential>, Self::StorageError> {
+        Ok(self.storage_manager.get_emergency_credential(typ).await?)
+    }
+
+    async fn insert_emergency_credential(
+        &self,
+        credential: &EmergencyCredentialContent,
+    ) -> Result<(), Self::StorageError> {
+        self.storage_manager
+            .insert_emergency_credential(credential)
+            .await?;
+        Ok(())
+    }
+
+    async fn remove_emergency_credential(&self, id: i64) -> Result<(), Self::StorageError> {
+        self.storage_manager.remove_emergency_credential(id).await?;
+        Ok(())
+    }
+
+    async fn remove_emergency_credentials_of_type(
+        &self,
+        typ: &str,
+    ) -> Result<(), Self::StorageError> {
+        self.storage_manager
+            .remove_emergency_credentials_of_type(typ)
+            .await?;
+        Ok(())
+    }
 }
@@ -1,7 +1,10 @@
 // Copyright 2022-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use crate::models::{BasicTicketbookInformation, RetrievedPendingTicketbook, RetrievedTicketbook};
+use crate::models::{
+    BasicTicketbookInformation, EmergencyCredential, EmergencyCredentialContent,
+    RetrievedPendingTicketbook, RetrievedTicketbook,
+};
 use async_trait::async_trait;
 use nym_compact_ecash::VerificationKeyAuth;
 use nym_credentials::ecash::bandwidth::serialiser::keys::EpochVerificationKey;
@@ -108,4 +111,21 @@ pub trait Storage: Clone + Send + Sync {
        &self,
        signatures: &AggregatedExpirationDateSignatures,
    ) -> Result<(), Self::StorageError>;
+
+    async fn get_emergency_credential(
+        &self,
+        typ: &str,
+    ) -> Result<Option<EmergencyCredential>, Self::StorageError>;
+
+    async fn insert_emergency_credential(
+        &self,
+        credential: &EmergencyCredentialContent,
+    ) -> Result<(), Self::StorageError>;
+
+    async fn remove_emergency_credential(&self, id: i64) -> Result<(), Self::StorageError>;
+
+    async fn remove_emergency_credentials_of_type(
+        &self,
+        typ: &str,
+    ) -> Result<(), Self::StorageError>;
 }
@@ -17,7 +17,6 @@ cosmwasm-std = { workspace = true }
 cw-utils = { workspace = true }
 dyn-clone = { workspace = true }
 futures = { workspace = true }
-rand = { workspace = true }
 si-scale = { workspace = true }
 thiserror = { workspace = true }
 tokio = { workspace = true, features = ["rt-multi-thread", "macros"] }
@@ -27,8 +26,11 @@ tracing = { workspace = true }
 nym-api-requests = { path = "../../nym-api/nym-api-requests" }
 nym-credentials = { path = "../credentials" }
 nym-credentials-interface = { path = "../credentials-interface" }
+nym-crypto = { path = "../crypto", features = ["asymmetric"] }
 nym-ecash-contract-common = { path = "../cosmwasm-smart-contracts/ecash-contract" }
 nym-gateway-requests = { path = "../gateway-requests" }
 nym-gateway-storage = { path = "../gateway-storage" }
+nym-metrics = { path = "../nym-metrics" }
 nym-task = { path = "../task" }
 nym-validator-client = { path = "../client-libs/validator-client" }
+nym-upgrade-mode-check = { path = "../upgrade-mode-check" }
@@ -6,7 +6,6 @@ use crate::ClientBandwidth;
 use crate::error::*;
 use nym_credentials::ecash::utils::ecash_today;
 use nym_credentials_interface::Bandwidth;
-use nym_gateway_requests::ServerResponse;
 use nym_gateway_storage::traits::BandwidthGatewayStorage;
 use si_scale::helpers::bibytes2;
 use time::OffsetDateTime;
@@ -66,7 +65,7 @@ impl BandwidthStorageManager {
        Ok(())
    }

-    pub async fn handle_claim_testnet_bandwidth(&mut self) -> Result<ServerResponse> {
+    pub async fn handle_claim_testnet_bandwidth(&mut self) -> Result<i64> {
        debug!("handling testnet bandwidth request");

        if self.only_coconut_credentials {
@@ -76,8 +75,7 @@ impl BandwidthStorageManager {
        self.increase_bandwidth(FREE_TESTNET_BANDWIDTH_VALUE, ecash_today())
            .await?;
        let available_total = self.client_bandwidth.available().await;
-
-        Ok(ServerResponse::Bandwidth { available_total })
+        Ok(available_total)
    }

    #[instrument(skip_all)]
@@ -96,7 +94,7 @@ impl BandwidthStorageManager {

        let available_bi2 = bibytes2(available_bandwidth as f64);
        let required_bi2 = bibytes2(required_bandwidth as f64);
-        debug!(available = available_bi2, required = required_bi2);
+        trace!(available = available_bi2, required = required_bi2);

        self.consume_bandwidth(required_bandwidth).await?;
        let remaining_bandwidth = self.client_bandwidth.available().await;
@@ -59,9 +59,13 @@ impl traits::EcashManager for EcashManager {
            .verify(aggregated_verification_key)
            .map_err(|err| match err {
                CompactEcashError::ExpirationDateSignatureValidity => {
+                    nym_metrics::inc!("ecash_verification_failures_invalid_date_signature");
                    EcashTicketError::MalformedTicketInvalidDateSignatures
                }
-                _ => EcashTicketError::MalformedTicket,
+                _ => {
+                    nym_metrics::inc!("ecash_verification_failures_signature");
+                    EcashTicketError::MalformedTicket
+                }
            })?;

        self.insert_pay_info(credential.pay_info.into(), insert_index)
@@ -249,4 +253,8 @@ impl traits::EcashManager for MockEcashManager {
    }

    fn async_verify(&self, _ticket: ClientTicket) {}
+
+    fn is_mock(&self) -> bool {
+        true
+    }
 }
@@ -222,9 +222,13 @@ impl SharedState {
            RwLockReadGuard::try_map(guard, |data| data.get(&epoch_id).map(|d| &d.master_key))
        {
            trace!("we already had cached api clients for epoch {epoch_id}");
+            nym_metrics::inc!("ecash_verification_key_cache_hits");
            return Ok(mapped);
        }

+        // Cache miss - need to fetch and set epoch data
+        nym_metrics::inc!("ecash_verification_key_cache_misses");
+
        let write_guard = self.set_epoch_data(epoch_id).await?;
        let guard = write_guard.downgrade();

@@ -20,4 +20,10 @@ pub trait EcashManager {
        aggregated_verification_key: &VerificationKeyAuth,
    ) -> Result<(), EcashTicketError>;
    fn async_verify(&self, ticket: ClientTicket);
+
+    /// Returns true if this is a mock ecash manager (for local testing).
+    /// Default implementation returns false.
+    fn is_mock(&self) -> bool {
+        false
+    }
 }
@@ -47,6 +47,25 @@ pub enum Error {
    UnknownTicketType(#[from] nym_credentials_interface::UnknownTicketType),
 }

+impl Error {
+    pub fn is_out_of_bandwidth(&self) -> bool {
+        matches!(self, Error::OutOfBandwidth { .. })
+    }
+}
+
+pub trait OutOfBandwidthResultExt {
+    fn is_out_of_bandwidth(&self) -> bool;
+}
+
+impl<T> OutOfBandwidthResultExt for Result<T> {
+    fn is_out_of_bandwidth(&self) -> bool {
+        match &self {
+            Ok(_) => false,
+            Err(err) => err.is_out_of_bandwidth(),
+        }
+    }
+}
+
 impl From<EcashTicketError> for Error {
    fn from(err: EcashTicketError) -> Self {
        // don't expose storage issue details to the user
@@ -8,16 +8,23 @@ use nym_credentials::ecash::utils::{EcashTime, cred_exp_date, ecash_today};
 use nym_credentials_interface::{Bandwidth, ClientTicket, TicketType};
 use nym_gateway_requests::models::CredentialSpendingRequest;
 use std::sync::Arc;
+use std::time::Instant;
 use time::{Date, OffsetDateTime};
 use tracing::*;

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

 pub mod bandwidth_storage_manager;
 mod client_bandwidth;
 pub mod ecash;
 pub mod error;
+pub mod upgrade_mode;
+
+// Histogram buckets for ecash verification duration (in seconds)
+const ECASH_VERIFICATION_DURATION_BUCKETS: &[f64] =
+    &[0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 2.0, 5.0];

 pub struct CredentialVerifier {
    credential: CredentialSpendingRequest,
@@ -62,6 +69,7 @@ impl CredentialVerifier {
            .await?;
        if spent {
            trace!("the credential has already been spent before at this gateway");
+            nym_metrics::inc!("ecash_verification_failures_double_spending");
            return Err(Error::BandwidthCredentialAlreadySpent);
        }
        Ok(())
@@ -103,6 +111,9 @@ impl CredentialVerifier {
    }

    pub async fn verify(&mut self) -> Result<i64> {
+        let start = Instant::now();
+        nym_metrics::inc!("ecash_verification_attempts");
+
        let received_at = OffsetDateTime::now_utc();
        let spend_date = ecash_today();

@@ -111,15 +122,39 @@ impl CredentialVerifier {
        let credential_type = TicketType::try_from_encoded(self.credential.data.payment.t_type)?;

        if self.credential.data.payment.spend_value != 1 {
+            nym_metrics::inc!("ecash_verification_failures_multiple_tickets");
            return Err(Error::MultipleTickets);
        }

-        self.check_credential_spending_date(spend_date.ecash_date())?;
+        if let Err(e) = self.check_credential_spending_date(spend_date.ecash_date()) {
+            nym_metrics::inc!("ecash_verification_failures_invalid_spend_date");
+            return Err(e);
+        }
+
        self.check_local_db_for_double_spending(&serial_number)
            .await?;

        // TODO: do we HAVE TO do it?
-        self.cryptographically_verify_ticket().await?;
+        let verify_result = self.cryptographically_verify_ticket().await;
+
+        // Track verification duration
+        let duration = start.elapsed().as_secs_f64();
+        nym_metrics::add_histogram_obs!(
+            "ecash_verification_duration_seconds",
+            duration,
+            ECASH_VERIFICATION_DURATION_BUCKETS
+        );
+
+        // Track epoch ID - use dynamic metric name via registry
+        let epoch_id = self.credential.data.epoch_id;
+        let epoch_metric = format!(
+            "nym_credential_verification_ecash_epoch_{}_verifications",
+            epoch_id
+        );
+        nym_metrics::metrics_registry().maybe_register_and_inc(&epoch_metric, None);
+
+        // Check verification result after timing
+        verify_result?;

        let ticket_id = self.store_received_ticket(received_at).await?;
        self.async_verify_ticket(ticket_id);
@@ -133,6 +168,8 @@ impl CredentialVerifier {
            .increase_bandwidth(bandwidth, cred_exp_date())
            .await?;

+        nym_metrics::inc!("ecash_verification_success");
+
        Ok(self
            .bandwidth_storage_manager
            .client_bandwidth
@@ -0,0 +1,293 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use futures::channel::mpsc::{UnboundedReceiver, UnboundedSender};
+use nym_crypto::asymmetric::ed25519;
+use nym_upgrade_mode_check::{
+    CREDENTIAL_PROXY_JWT_ISSUER, UpgradeModeAttestation, validate_upgrade_mode_jwt,
+};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicI64, Ordering};
+use std::time::Duration;
+use thiserror::Error;
+use time::OffsetDateTime;
+use tokio::sync::{Notify, RwLock};
+use tracing::{debug, error, info};
+
+#[derive(Debug, Error)]
+pub enum UpgradeModeEnableError {
+    #[error("too soon to perform another upgrade mode attestation check")]
+    TooManyRecheckRequests,
+
+    #[error("provided upgrade mode JWT is invalid: {0}")]
+    InvalidUpgradeModeJWT(#[from] nym_upgrade_mode_check::UpgradeModeCheckError),
+
+    #[error("the upgrade mode attestation does not appear to have been published")]
+    AttestationNotPublished,
+
+    #[error("the provided upgrade mode attestation is different from the published one")]
+    MismatchedUpgradeModeAttestation,
+}
+
+// the idea behind this is as follows:
+// it's been relatively a long time since the watcher last performed its checks (since it's in 'regular' mode)
+// and some client has just sent a JWT. we have to retrieve most recent information in case upgrade mode
+// has just been enabled, and we haven't learned about it yet
+#[derive(Clone)]
+pub struct UpgradeModeCheckRequestSender(Option<UnboundedSender<CheckRequest>>);
+
+impl UpgradeModeCheckRequestSender {
+    pub fn new(sender: UnboundedSender<CheckRequest>) -> Self {
+        UpgradeModeCheckRequestSender(Some(sender))
+    }
+
+    pub fn new_empty() -> Self {
+        Self(None)
+    }
+
+    pub(crate) fn send_request(&self, on_done: Arc<Notify>) {
+        let Some(ref inner) = self.0 else {
+            // make sure the caller gets notified so it doesn't wait forever
+            on_done.notify_waiters();
+            return;
+        };
+
+        if let Err(not_sent) = inner.unbounded_send(CheckRequest { on_done }) {
+            debug!("failed to send upgrade mode check request - {not_sent}");
+            // make sure the caller gets notified so it doesn't wait forever
+            not_sent.into_inner().on_done.notify_waiters();
+        }
+    }
+}
+
+pub type UpgradeModeCheckRequestReceiver = UnboundedReceiver<CheckRequest>;
+
+pub struct CheckRequest {
+    on_done: Arc<Notify>,
+}
+
+impl CheckRequest {
+    pub fn finalize(self) {
+        self.on_done.notify_waiters();
+    }
+}
+
+#[derive(Clone, Copy)]
+pub struct UpgradeModeCheckConfig {
+    /// The minimum duration since the last explicit check to allow creation of separate request.
+    pub min_staleness_recheck: Duration,
+}
+
+/// Full upgrade mode information, that apart from boolean flag indicating the state
+/// and the attestation information, includes channel connection to relevant
+/// attestation watcher to request state rechecks
+#[derive(Clone)]
+pub struct UpgradeModeDetails {
+    pub(crate) config: UpgradeModeCheckConfig,
+    pub(crate) request_checker: UpgradeModeCheckRequestSender,
+    pub(crate) state: UpgradeModeState,
+}
+
+impl UpgradeModeDetails {
+    pub fn new(
+        config: UpgradeModeCheckConfig,
+        request_checker: UpgradeModeCheckRequestSender,
+        state: UpgradeModeState,
+    ) -> Self {
+        UpgradeModeDetails {
+            config,
+            request_checker,
+            state,
+        }
+    }
+
+    pub fn state(&self) -> &UpgradeModeState {
+        &self.state
+    }
+
+    pub fn enabled(&self) -> bool {
+        self.state.upgrade_mode_enabled()
+    }
+
+    fn since_last_query(&self) -> Duration {
+        self.state.since_last_query()
+    }
+
+    pub fn can_request_recheck(&self) -> bool {
+        self.since_last_query() > self.config.min_staleness_recheck
+    }
+
+    // explicitly request state update. this is only called when upgrade mode is NOT enabled,
+    // and client has sent a JWT instead of ticket
+    async fn request_recheck(&self) -> bool {
+        // send request
+        let on_done = Arc::new(Notify::new());
+        self.request_checker.send_request(on_done.clone());
+
+        // wait for response - note, if we fail to send, notification will be sent regardless,
+        // so that we wouldn't get stuck in here
+        on_done.notified().await;
+
+        // check the state again
+        self.enabled()
+    }
+
+    pub async fn try_enable_via_received_jwt(
+        &self,
+        token: String,
+    ) -> Result<(), UpgradeModeEnableError> {
+        // see if it's viable to perform another expedited check
+        if !self.can_request_recheck() {
+            return Err(UpgradeModeEnableError::TooManyRecheckRequests);
+        }
+
+        // first validate whether the received JWT is even valid
+        let attestation = validate_upgrade_mode_jwt(&token, Some(CREDENTIAL_PROXY_JWT_ISSUER))?;
+
+        // send request to revalidate internal state
+        // this will, among other things, pull fresh attestation from the configured endpoint
+        // and also verify required signatures (and pubkeys)
+        self.request_recheck().await;
+
+        // not strictly necessary, but check if provided attestation actually matches the one retrieved
+        // (if any)
+        let Some(retrieved_attestation) = self.state.attestation().await else {
+            return Err(UpgradeModeEnableError::AttestationNotPublished);
+        };
+        if retrieved_attestation != attestation {
+            return Err(UpgradeModeEnableError::MismatchedUpgradeModeAttestation);
+        }
+
+        // note: if attestation has been returned, it means we're definitely in upgrade mode
+        // (otherwise it wouldn't have existed in the state)
+        info!("managed to initialise upgrade mode through received JWT");
+
+        Ok(())
+    }
+}
+
+/// Detailed upgrade mode information, that apart from boolean flag,
+/// also includes, if applicable, the associated attestation
+#[derive(Clone)]
+pub struct UpgradeModeState {
+    inner: Arc<UpgradeModeStateInner>,
+}
+
+/// Just a shareable flag to indicate whether upgrade mode is enabled or disabled
+#[derive(Clone, Default)]
+pub struct UpgradeModeStatus(Arc<AtomicBool>);
+
+impl UpgradeModeStatus {
+    pub fn enabled(&self) -> bool {
+        self.0.load(Ordering::Acquire)
+    }
+
+    pub fn enable(&self) {
+        self.0.store(true, Ordering::Relaxed);
+    }
+
+    pub fn disable(&self) {
+        self.0.store(false, Ordering::Release);
+    }
+}
+
+impl UpgradeModeState {
+    pub fn new(attester_public_key: ed25519::PublicKey) -> UpgradeModeState {
+        UpgradeModeState {
+            inner: Arc::new(UpgradeModeStateInner {
+                expected_attester_public_key: attester_public_key,
+                expected_attestation: RwLock::new(None),
+                last_queried_ts: AtomicI64::new(OffsetDateTime::UNIX_EPOCH.unix_timestamp()),
+                status: UpgradeModeStatus(Arc::new(AtomicBool::new(false))),
+            }),
+        }
+    }
+
+    pub fn attester_pubkey(&self) -> ed25519::PublicKey {
+        self.inner.expected_attester_public_key
+    }
+
+    pub async fn attestation(&self) -> Option<UpgradeModeAttestation> {
+        self.inner.expected_attestation.read().await.clone()
+    }
+
+    pub async fn try_set_expected_attestation(
+        &self,
+        expected_attestation: Option<UpgradeModeAttestation>,
+    ) {
+        // make sure to only enable upgrade mode flag AFTER we have written the expected value
+        // (or still hold the exclusive lock as in this instance)
+        let mut guard = self.inner.expected_attestation.write().await;
+
+        // ensure that the attestation had been signed with the expected key
+        if let Some(attestation) = expected_attestation.as_ref() {
+            if attestation.content.attester_public_key != self.inner.expected_attester_public_key {
+                self.update_last_queried(OffsetDateTime::now_utc());
+                return;
+            }
+
+            self.enable_upgrade_mode()
+        } else {
+            self.disable_upgrade_mode()
+        }
+
+        self.update_last_queried(OffsetDateTime::now_utc());
+        *guard = expected_attestation;
+    }
+
+    pub fn upgrade_mode_status(&self) -> UpgradeModeStatus {
+        self.inner.status.clone()
+    }
+
+    pub fn upgrade_mode_enabled(&self) -> bool {
+        self.inner.status.enabled()
+    }
+
+    pub fn enable_upgrade_mode(&self) {
+        self.inner.status.enable()
+    }
+
+    pub fn disable_upgrade_mode(&self) {
+        self.inner.status.disable()
+    }
+
+    pub fn last_queried(&self) -> OffsetDateTime {
+        // SAFETY: the stored value here is always a valid unix timestamp
+        #[allow(clippy::unwrap_used)]
+        OffsetDateTime::from_unix_timestamp(self.inner.last_queried_ts.load(Ordering::Acquire))
+            .unwrap()
+    }
+
+    pub fn update_last_queried(&self, queried_at: OffsetDateTime) {
+        self.inner
+            .last_queried_ts
+            .store(queried_at.unix_timestamp(), Ordering::Release);
+    }
+
+    pub fn since_last_query(&self) -> Duration {
+        (OffsetDateTime::now_utc() - self.last_queried())
+            .try_into()
+            .unwrap_or_else(|_| {
+                error!("somehow our last query for upgrade mode was in the future!");
+                Duration::ZERO
+            })
+    }
+}
+
+struct UpgradeModeStateInner {
+    /// Expected public key of the entity issuing upgrade mode attestations.
+    expected_attester_public_key: ed25519::PublicKey,
+
+    /// Contents of the published upgrade mode attestation, as queried by this node
+    expected_attestation: RwLock<Option<UpgradeModeAttestation>>,
+
+    /// timestamp indicating last time this node has queried for the current upgrade mode attestation
+    /// it is used to determine if an additional expedited query should be made in case client sends a JWT
+    /// whilst this node is not aware of the upgrade mode
+    last_queried_ts: AtomicI64,
+
+    /// flag indicating whether upgrade mode is currently enabled. this is to perform cheap checks
+    /// that avoid having to acquire the lock
+    // (and dealing with the async consequences of that)
+    status: UpgradeModeStatus,
+}
@@ -23,3 +23,5 @@ rand = { workspace = true }
 nym-compact-ecash = { path = "../nym_offline_compact_ecash" }
 nym-ecash-time = { path = "../ecash-time" }
 nym-network-defaults = { path = "../network-defaults" }
+nym-upgrade-mode-check = { path = "../upgrade-mode-check" }
+
@@ -30,6 +30,35 @@ pub use nym_compact_ecash::{
 };
 pub use nym_ecash_time::{EcashTime, ecash_today};
 pub use nym_network_defaults::TicketTypeRepr;
+use nym_network_defaults::TicketTypeRepr::V1MixnetEntry;
+
+/// Default bandwidth amount under which [mixnet] clients will attempt to send additional zk-nyms
+/// to increase their allowance.
+// currently defined as 20% of entry ticket value
+// clients are, of course, free to override this value
+pub const DEFAULT_MIXNET_REQUEST_BANDWIDTH_THRESHOLD: i64 =
+    (V1MixnetEntry.bandwidth_value() / 5) as i64;
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub enum BandwidthCredential {
+    ZkNym(Box<CredentialSpendingData>),
+    UpgradeModeJWT { token: String },
+}
+
+impl BandwidthCredential {
+    pub fn into_zk_nym(self) -> Option<Box<CredentialSpendingData>> {
+        match self {
+            BandwidthCredential::ZkNym(credential) => Some(credential),
+            _ => None,
+        }
+    }
+}
+
+impl From<CredentialSpendingData> for BandwidthCredential {
+    fn from(credential: CredentialSpendingData) -> Self {
+        Self::ZkNym(Box::new(credential))
+    }
+}

 #[derive(Debug, Clone)]
 pub struct CredentialSigningData {
@@ -15,6 +15,7 @@ base64.workspace = true
 bs58 = { workspace = true }
 blake3 = { workspace = true, features = ["traits-preview"], optional = true }
 ctr = { workspace = true, optional = true }
+curve25519-dalek = { workspace = true, optional = true }
 digest = { workspace = true, optional = true }
 generic-array = { workspace = true, optional = true }
 hkdf = { workspace = true, optional = true }
@@ -36,14 +37,18 @@ nym-sphinx-types = { path = "../nymsphinx/types", version = "0.2.0", default-fea
 nym-pemstore = { path = "../../common/pemstore", version = "0.3.0" }

 [dev-dependencies]
+anyhow = { workspace = true }
 rand_chacha = { workspace = true }
+serde_json = { workspace = true }
+nym-test-utils = { path = "../test-utils" }
+

 [features]
 default = []
 aead = ["dep:aead", "aead/std", "aes-gcm-siv", "generic-array"]
 naive_jwt = ["asymmetric", "jwt-simple"]
 serde = ["dep:serde", "serde_bytes", "ed25519-dalek/serde", "x25519-dalek/serde"]
-asymmetric = ["x25519-dalek", "ed25519-dalek", "zeroize"]
+asymmetric = ["x25519-dalek", "ed25519-dalek", "curve25519-dalek", "sha2", "zeroize"]
 hashing = ["blake3", "digest", "hkdf", "hmac", "generic-array", "sha2"]
 stream_cipher = ["aes", "ctr", "cipher", "generic-array"]
 sphinx = ["nym-sphinx-types/sphinx"]
@@ -213,6 +213,37 @@ impl PublicKey {
    ) -> Result<(), SignatureError> {
        self.0.verify(message.as_ref(), &signature.0)
    }
+
+    /// Converts this Ed25519 public key to an X25519 public key for ECDH.
+    ///
+    /// Uses the standard ed25519→x25519 conversion by converting the Edwards point
+    /// to Montgomery form. This is the same approach as libsodium's
+    /// `crypto_sign_ed25519_pk_to_curve25519`.
+    ///
+    /// # Returns
+    /// * `Ok(x25519::PublicKey)` - The converted X25519 public key
+    /// * `Err(Ed25519RecoveryError)` - If the conversion fails (e.g., low-order point)
+    pub fn to_x25519(&self) -> Result<crate::asymmetric::x25519::PublicKey, Ed25519RecoveryError> {
+        use curve25519_dalek::edwards::CompressedEdwardsY;
+
+        // Decompress the Ed25519 point
+        let compressed = CompressedEdwardsY((*self).to_bytes());
+        let edwards_point = compressed.decompress().ok_or_else(|| {
+            Ed25519RecoveryError::MalformedBytes(SignatureError::from_source(
+                "Failed to decompress Ed25519 point".to_string(),
+            ))
+        })?;
+
+        // Convert to Montgomery form
+        let montgomery = edwards_point.to_montgomery();
+
+        // Create X25519 public key
+        crate::asymmetric::x25519::PublicKey::from_bytes(montgomery.as_bytes()).map_err(|_| {
+            Ed25519RecoveryError::MalformedBytes(SignatureError::from_source(
+                "Failed to convert to X25519".to_string(),
+            ))
+        })
+    }
 }

 #[cfg(feature = "sphinx")]
@@ -334,6 +365,28 @@ impl PrivateKey {
        let signature_bytes = self.sign(text).to_bytes();
        bs58::encode(signature_bytes).into_string()
    }
+
+    /// Converts this Ed25519 private key to an X25519 private key for ECDH.
+    ///
+    /// Uses the standard ed25519→x25519 conversion via SHA-512 hash and clamping.
+    /// This is the same approach as libsodium's `crypto_sign_ed25519_sk_to_curve25519`.
+    ///
+    /// # Returns
+    /// The converted X25519 private key
+    pub fn to_x25519(&self) -> crate::asymmetric::x25519::PrivateKey {
+        use sha2::{Digest, Sha512};
+
+        // Hash the Ed25519 secret key with SHA-512
+        let hash = Sha512::digest(self.0);
+
+        // Take first 32 bytes (clamping is done automatically by x25519_dalek::StaticSecret)
+        let mut x25519_bytes = [0u8; 32];
+        x25519_bytes.copy_from_slice(&hash[..32]);
+
+        #[allow(clippy::expect_used)]
+        crate::asymmetric::x25519::PrivateKey::from_bytes(&x25519_bytes)
+            .expect("x25519 key conversion should never fail")
+    }
 }

 #[cfg(feature = "serde")]
@@ -517,4 +570,27 @@ mod tests {

        assert_eq!(sig1.to_vec(), sig2);
    }
+
+    #[test]
+    #[cfg(feature = "rand")]
+    fn test_ed25519_to_x25519_ecdh() {
+        let mut rng = thread_rng();
+
+        // Create two ed25519 keypairs
+        let alice_ed = KeyPair::new(&mut rng);
+        let bob_ed = KeyPair::new(&mut rng);
+
+        // Convert to x25519
+        let alice_x25519_private = alice_ed.private_key().to_x25519();
+        let alice_x25519_public = alice_ed.public_key().to_x25519().unwrap();
+        let bob_x25519_private = bob_ed.private_key().to_x25519();
+        let bob_x25519_public = bob_ed.public_key().to_x25519().unwrap();
+
+        // Perform ECDH both ways
+        let alice_shared = alice_x25519_private.diffie_hellman(&bob_x25519_public);
+        let bob_shared = bob_x25519_private.diffie_hellman(&alice_x25519_public);
+
+        // Both should produce the same shared secret
+        assert_eq!(alice_shared, bob_shared);
+    }
 }
@@ -17,6 +17,51 @@ pub mod bs58_ed25519_pubkey {
    }
 }

+pub mod vec_bs58_ed25519_pubkey {
+    use super::*;
+    use serde::{Deserialize, Deserializer, Serializer, ser::SerializeSeq};
+
+    pub fn serialize<S: Serializer>(
+        keys: &Vec<PublicKey>,
+        serializer: S,
+    ) -> Result<S::Ok, S::Error> {
+        let mut seq = serializer.serialize_seq(Some(keys.len()))?;
+        for key in keys {
+            seq.serialize_element(&Bs58KeyWrapper(*key))?;
+        }
+        seq.end()
+    }
+
+    pub fn deserialize<'de, D: Deserializer<'de>>(
+        deserializer: D,
+    ) -> Result<Vec<PublicKey>, D::Error> {
+        let wrapped = Vec::<Bs58KeyWrapper>::deserialize(deserializer)?;
+        Ok(wrapped.into_iter().map(|k| k.0).collect())
+    }
+
+    struct Bs58KeyWrapper(PublicKey);
+
+    impl serde::Serialize for Bs58KeyWrapper {
+        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+        where
+            S: Serializer,
+        {
+            bs58_ed25519_pubkey::serialize(&self.0, serializer)
+        }
+    }
+
+    impl<'de> Deserialize<'de> for Bs58KeyWrapper {
+        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+        where
+            D: Deserializer<'de>,
+        {
+            Ok(Bs58KeyWrapper(bs58_ed25519_pubkey::deserialize(
+                deserializer,
+            )?))
+        }
+    }
+}
+
 pub mod bs58_ed25519_signature {
    use crate::asymmetric::ed25519::Signature;
    use serde::{Deserialize, Deserializer, Serializer};
@@ -33,3 +78,53 @@ pub mod bs58_ed25519_signature {
        Signature::from_base58_string(s).map_err(serde::de::Error::custom)
    }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use jwt_simple::reexports::{anyhow, serde_json};
+    use nym_test_utils::helpers::deterministic_rng;
+    use serde::{Deserialize, Serialize};
+
+    #[test]
+    fn vec_bs58_ed25519_pubkey_json() -> anyhow::Result<()> {
+        #[derive(Serialize, Deserialize, Debug, PartialEq)]
+        struct KeysWrapper(#[serde(with = "vec_bs58_ed25519_pubkey")] Vec<PublicKey>);
+
+        use crate::asymmetric::ed25519;
+        let mut rng = deterministic_rng();
+        let empty = KeysWrapper(vec![]);
+        let single_key = KeysWrapper(vec![PublicKey::from_base58_string(
+            "Be9wH7xuXBRJAuV1pC7MALZv6a61RvWQ3SypsNarqTt",
+        )?]);
+        let three_keys = KeysWrapper(vec![
+            ed25519::KeyPair::new(&mut rng).public_key,
+            ed25519::KeyPair::new(&mut rng).public_key,
+            ed25519::KeyPair::new(&mut rng).public_key,
+        ]);
+
+        let se_empty = serde_json::to_string(&empty)?;
+        let se_single_key = serde_json::to_string(&single_key)?;
+        let se_three_keys = serde_json::to_string(&three_keys)?;
+
+        assert_eq!(se_empty, r#"[]"#);
+        assert_eq!(
+            se_single_key,
+            r#"["Be9wH7xuXBRJAuV1pC7MALZv6a61RvWQ3SypsNarqTt"]"#
+        );
+        assert_eq!(
+            se_three_keys,
+            r#"["HmgHDV79LpnEaSUp8QZQwSroxVvS4RewF7yM9e7qu8y3","311xRh859qCd5MVqoPRCoNx26eYhLknGwtjzkkTJFGhf","A5BMp8WJ6Uk91U4JpWRv2Bc6X35AaRaSEy8QEWeAkaBv"]"#
+        );
+
+        let empty_de = serde_json::from_str::<KeysWrapper>(&se_empty)?;
+        let single_key_de = serde_json::from_str::<KeysWrapper>(&se_single_key)?;
+        let three_keys_de = serde_json::from_str::<KeysWrapper>(&se_three_keys)?;
+
+        assert_eq!(empty, empty_de);
+        assert_eq!(single_key, single_key_de);
+        assert_eq!(three_keys, three_keys_de);
+
+        Ok(())
+    }
+}
@@ -0,0 +1,98 @@
+// Copyright 2025 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+//! Key Derivation Functions using Blake3.
+
+/// Derives a 32-byte key using Blake3's key derivation mode.
+///
+/// Uses Blake3's built-in `derive_key` function with domain separation via context string.
+///
+/// # Arguments
+/// * `context` - Context string for domain separation (e.g., "nym-lp-psk-v1")
+/// * `key_material` - Input key material (shared secret from ECDH, etc.)
+/// * `salt` - Additional salt for freshness (timestamp + nonce)
+///
+/// # Returns
+/// 32-byte derived key suitable for use as PSK
+///
+/// # Example
+/// ```ignore
+/// let psk = derive_key_blake3("nym-lp-psk-v1", shared_secret.as_bytes(), &salt);
+/// ```
+pub fn derive_key_blake3(context: &str, key_material: &[u8], salt: &[u8]) -> [u8; 32] {
+    // Concatenate key_material and salt as input
+    let input = [key_material, salt].concat();
+
+    // Use Blake3's derive_key with context for domain separation
+    // blake3::derive_key returns [u8; 32] directly
+    blake3::derive_key(context, &input)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_deterministic_derivation() {
+        let context = "test-context";
+        let key_material = b"shared_secret_12345";
+        let salt = b"salt_67890";
+
+        let key1 = derive_key_blake3(context, key_material, salt);
+        let key2 = derive_key_blake3(context, key_material, salt);
+
+        assert_eq!(key1, key2, "Same inputs should produce same output");
+    }
+
+    #[test]
+    fn test_different_contexts_produce_different_keys() {
+        let key_material = b"shared_secret";
+        let salt = b"salt";
+
+        let key1 = derive_key_blake3("context1", key_material, salt);
+        let key2 = derive_key_blake3("context2", key_material, salt);
+
+        assert_ne!(
+            key1, key2,
+            "Different contexts should produce different keys"
+        );
+    }
+
+    #[test]
+    fn test_different_salts_produce_different_keys() {
+        let context = "test-context";
+        let key_material = b"shared_secret";
+
+        let key1 = derive_key_blake3(context, key_material, b"salt1");
+        let key2 = derive_key_blake3(context, key_material, b"salt2");
+
+        assert_ne!(key1, key2, "Different salts should produce different keys");
+    }
+
+    #[test]
+    fn test_different_key_material_produces_different_keys() {
+        let context = "test-context";
+        let salt = b"salt";
+
+        let key1 = derive_key_blake3(context, b"secret1", salt);
+        let key2 = derive_key_blake3(context, b"secret2", salt);
+
+        assert_ne!(
+            key1, key2,
+            "Different key material should produce different keys"
+        );
+    }
+
+    #[test]
+    fn test_output_length() {
+        let key = derive_key_blake3("test", b"key", b"salt");
+        assert_eq!(key.len(), 32, "Output should be exactly 32 bytes");
+    }
+
+    #[test]
+    fn test_empty_inputs() {
+        // Should not panic with empty inputs
+        let key = derive_key_blake3("test", b"", b"");
+        assert_eq!(key.len(), 32);
+    }
+}
@@ -10,6 +10,8 @@ pub mod crypto_hash;
 pub mod hkdf;
 #[cfg(feature = "hashing")]
 pub mod hmac;
+#[cfg(feature = "hashing")]
+pub mod kdf;
 #[cfg(all(feature = "asymmetric", feature = "hashing", feature = "stream_cipher"))]
 pub mod shared_key;
 pub mod symmetric;
@@ -51,3 +51,6 @@ anyhow = { workspace = true }
 nym-compact-ecash = { path = "../nym_offline_compact_ecash" } # we need specific imports in tests
 nym-test-utils = { path = "../test-utils" }
 tokio = { workspace = true, features = ["full"] }
+
+[lints]
+workspace = true
@@ -19,7 +19,9 @@ pub use shared_key::{
    SharedGatewayKey, SharedKeyConversionError, SharedKeyUsageError, SharedSymmetricKey,
 };

-pub const CURRENT_PROTOCOL_VERSION: u8 = EMBEDDED_KEY_ROTATION_INFO_VERSION;
+pub type GatewayProtocolVersion = u8;
+
+pub const CURRENT_PROTOCOL_VERSION: GatewayProtocolVersion = UPGRADE_MODE_VERSION;

 /// Defines the current version of the communication protocol between gateway and clients.
 /// It has to be incremented for any breaking change.
@@ -29,35 +31,73 @@ pub const CURRENT_PROTOCOL_VERSION: u8 = EMBEDDED_KEY_ROTATION_INFO_VERSION;
 // 3 - change to AES-GCM-SIV and non-zero IVs
 // 4 - introduction of v2 authentication protocol to prevent reply attacks
 // 5 - add key rotation information to the serialised mix packet
-pub const INITIAL_PROTOCOL_VERSION: u8 = 1;
-pub const CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION: u8 = 2;
-pub const AES_GCM_SIV_PROTOCOL_VERSION: u8 = 3;
-pub const AUTHENTICATE_V2_PROTOCOL_VERSION: u8 = 4;
-pub const EMBEDDED_KEY_ROTATION_INFO_VERSION: u8 = 5;
+// 6 - support for 'upgrade mode'
+pub const INITIAL_PROTOCOL_VERSION: GatewayProtocolVersion = 1;
+pub const CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION: GatewayProtocolVersion = 2;
+pub const AES_GCM_SIV_PROTOCOL_VERSION: GatewayProtocolVersion = 3;
+pub const AUTHENTICATE_V2_PROTOCOL_VERSION: GatewayProtocolVersion = 4;
+pub const EMBEDDED_KEY_ROTATION_INFO_VERSION: GatewayProtocolVersion = 5;
+pub const UPGRADE_MODE_VERSION: GatewayProtocolVersion = 6;

 // TODO: could using `Mac` trait here for OutputSize backfire?
 // Should hmac itself be exposed, imported and used instead?
 pub type LegacyGatewayMacSize = <GatewayIntegrityHmacAlgorithm as OutputSizeUser>::OutputSize;

 pub trait GatewayProtocolVersionExt {
+    const CURRENT: GatewayProtocolVersion = CURRENT_PROTOCOL_VERSION;
+
    fn supports_aes256_gcm_siv(&self) -> bool;
    fn supports_authenticate_v2(&self) -> bool;
    fn supports_key_rotation_packet(&self) -> bool;
+    fn supports_upgrade_mode(&self) -> bool;
+    fn is_future_version(&self) -> bool;
 }

-impl GatewayProtocolVersionExt for Option<u8> {
+impl GatewayProtocolVersionExt for Option<GatewayProtocolVersion> {
    fn supports_aes256_gcm_siv(&self) -> bool {
-        let Some(protocol) = *self else { return false };
-        protocol >= AES_GCM_SIV_PROTOCOL_VERSION
+        let Some(protocol) = self else { return false };
+        protocol.supports_aes256_gcm_siv()
    }

    fn supports_authenticate_v2(&self) -> bool {
-        let Some(protocol) = *self else { return false };
-        protocol >= AUTHENTICATE_V2_PROTOCOL_VERSION
+        let Some(protocol) = self else { return false };
+        protocol.supports_authenticate_v2()
    }

    fn supports_key_rotation_packet(&self) -> bool {
-        let Some(protocol) = *self else { return false };
-        protocol >= EMBEDDED_KEY_ROTATION_INFO_VERSION
+        let Some(protocol) = self else { return false };
+        protocol.supports_key_rotation_packet()
+    }
+
+    fn supports_upgrade_mode(&self) -> bool {
+        let Some(protocol) = self else { return false };
+        protocol.supports_upgrade_mode()
+    }
+
+    fn is_future_version(&self) -> bool {
+        let Some(protocol) = self else { return false };
+        protocol.is_future_version()
+    }
+}
+
+impl GatewayProtocolVersionExt for GatewayProtocolVersion {
+    fn supports_aes256_gcm_siv(&self) -> bool {
+        *self >= AES_GCM_SIV_PROTOCOL_VERSION
+    }
+
+    fn supports_authenticate_v2(&self) -> bool {
+        *self >= AUTHENTICATE_V2_PROTOCOL_VERSION
+    }
+
+    fn supports_key_rotation_packet(&self) -> bool {
+        *self >= EMBEDDED_KEY_ROTATION_INFO_VERSION
+    }
+
+    fn supports_upgrade_mode(&self) -> bool {
+        *self >= UPGRADE_MODE_VERSION
+    }
+
+    fn is_future_version(&self) -> bool {
+        *self > CURRENT_PROTOCOL_VERSION
    }
 }
@@ -82,7 +82,7 @@ mod tests {
        let exp_date_sigs = generate_expiration_date_signatures(
            sig_req.expiration_date.ecash_unix_timestamp(),
            &[keypair.secret_key()],
-            &vec![keypair.verification_key()],
+            &[keypair.verification_key()],
            &keypair.verification_key(),
            &[keypair.index.unwrap()],
        )
@@ -106,14 +106,14 @@ mod tests {
            .unwrap();

        let wallet = issuance
-            .aggregate_signature_shares(&keypair.verification_key(), &vec![partial_wallet], sig_req)
+            .aggregate_signature_shares(&keypair.verification_key(), &[partial_wallet], sig_req)
            .unwrap();

        let mut issued = issuance.into_issued_ticketbook(wallet, 1);
        let coin_indices_signatures = generate_coin_indices_signatures(
            nym_credentials_interface::ecash_parameters(),
            &[keypair.secret_key()],
-            &vec![keypair.verification_key()],
+            &[keypair.verification_key()],
            &keypair.verification_key(),
            &[keypair.index.unwrap()],
        )
@@ -3,10 +3,12 @@

 use crate::registration::handshake::messages::{Finalization, GatewayMaterialExchange};
 use crate::registration::handshake::state::State;
-use crate::registration::handshake::SharedGatewayKey;
+use crate::registration::handshake::HandshakeResult;
 use crate::registration::handshake::{error::HandshakeError, WsItem};
+use crate::{GatewayProtocolVersionExt, INITIAL_PROTOCOL_VERSION};
 use futures::{Sink, Stream};
 use rand::{CryptoRng, RngCore};
+use tracing::info;
 use tungstenite::Message as WsMessage;

 impl<S, R> State<'_, S, R> {
@@ -25,10 +27,26 @@ impl<S, R> State<'_, S, R> {

        // 2. wait for response with remote x25519 pubkey as well as encrypted signature
        // <- g^y || AES(k, sig(gate_priv, (g^y || g^x)) || MAYBE_NONCE
-        let mid_res = self
+        let (mid_res, gateway_protocol) = self
            .receive_handshake_message::<GatewayMaterialExchange>()
            .await?;

+        // NEGOTIATE PROTOCOL
+        if gateway_protocol.is_future_version() {
+            // SAFETY: future version means it's greater than CURRENT, which is always a `Some`
+            #[allow(clippy::unwrap_used)]
+            return Err(HandshakeError::UnsupportedProtocol {
+                version: gateway_protocol.unwrap(),
+            });
+        }
+        let gateway_protocol = gateway_protocol.unwrap_or(INITIAL_PROTOCOL_VERSION);
+
+        // that should never happen, but we're fine with that outcome
+        if Some(gateway_protocol) != self.proposed_protocol_version() {
+            info!("the gateway insists on protocol version different from the one we suggested. it wants {gateway_protocol} whilst we wanted {:?}, however, we can support it", self.proposed_protocol_version());
+            self.set_protocol_version(gateway_protocol);
+        }
+
        // 3. derive shared keys locally
        // hkdf::<blake3>::(g^xy)
        self.derive_shared_key(&mid_res.ephemeral_dh, maybe_hkdf_salt.as_deref());
@@ -42,14 +60,14 @@ impl<S, R> State<'_, S, R> {
        self.send_handshake_data(materials).await?;

        // 6. wait for remote confirmation of finalizing the handshake
-        let finalization = self.receive_handshake_message::<Finalization>().await?;
+        let (finalization, _) = self.receive_handshake_message::<Finalization>().await?;
        finalization.ensure_success()?;
        Ok(())
    }

    pub(crate) async fn perform_client_handshake(
        mut self,
-    ) -> Result<SharedGatewayKey, HandshakeError>
+    ) -> Result<HandshakeResult, HandshakeError>
    where
        S: Stream<Item = WsItem> + Sink<WsMessage> + Unpin,
        R: CryptoRng + RngCore,
@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::shared_key::SharedKeyUsageError;
+use crate::GatewayProtocolVersion;
+use crate::GatewayProtocolVersionExt;
 use thiserror::Error;

 #[derive(Debug, Error)]
@@ -34,4 +36,10 @@ pub enum HandshakeError {

    #[error("timed out waiting for a handshake message")]
    Timeout,
+
+    #[error("Connection is in an invalid state - please send a bug report")]
+    ConnectionInInvalidState,
+
+    #[error("the gateway requests protocol version that's not supported by this client. it wants to use v{version} whilst we only understand up to v{}", GatewayProtocolVersion::CURRENT)]
+    UnsupportedProtocol { version: GatewayProtocolVersion },
 }
@@ -5,9 +5,11 @@ use crate::registration::handshake::messages::{
    HandshakeMessage, Initialisation, MaterialExchange,
 };
 use crate::registration::handshake::state::State;
-use crate::registration::handshake::SharedGatewayKey;
+use crate::registration::handshake::HandshakeResult;
 use crate::registration::handshake::{error::HandshakeError, WsItem};
+use crate::{GatewayProtocolVersion, GatewayProtocolVersionExt};
 use futures::{Sink, Stream};
+use tracing::{debug, warn};
 use tungstenite::Message as WsMessage;

 impl<S, R> State<'_, S, R> {
@@ -18,11 +20,39 @@ impl<S, R> State<'_, S, R> {
    where
        S: Stream<Item = WsItem> + Sink<WsMessage> + Unpin,
    {
+        // NEGOTIATE PROTOCOL
+        // old clients were sending protocol version as defined by the following:
+        /*
+          fn request_protocol_version(&self) -> u8 {
+               if self.derive_aes256_gcm_siv_key {
+                   AES_GCM_SIV_PROTOCOL_VERSION
+               } else if self.expects_credential_usage {
+                   CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION
+               } else {
+                   INITIAL_PROTOCOL_VERSION
+               }
+           }
+        */
+        // meaning the highest possible value they could have sent was `4` (AUTHENTICATE_V2_PROTOCOL_VERSION)
+        // so if we received anything higher than that, it means they understand negotiation.
+        // currently not strictly needed as we just blindly accept what they proposed,
+        // but will be needed in the future.
+        if self.proposed_protocol_version().is_future_version() {
+            // this should never happen in a non-malicious client as it should use at most whatever version this gateway has announced
+            self.set_protocol_version(GatewayProtocolVersion::CURRENT)
+        } else {
+            // currently we accept all protocols, i.e. legacy keys, aes128, etc. so we downgrade to whatever
+            // the client has proposed. this will change in the future
+            debug!(
+                "using the protocol version proposed by the client: {:?}",
+                self.proposed_protocol_version()
+            )
+        }
+
        // 1. receive remote ed25519 pubkey alongside ephemeral x25519 pubkey and maybe a flag indicating non-legacy client
        // LOCAL_ID_PUBKEY || EPHEMERAL_KEY || MAYBE_NON_LEGACY
        let init_message = Initialisation::try_from_bytes(&raw_init_message)?;
        self.update_remote_identity(init_message.identity);
-        self.set_aes256_gcm_siv_key_derivation(!init_message.is_legacy());

        // 2. derive shared keys locally
        // hkdf::<blake3>::(g^xy)
@@ -39,7 +69,12 @@ impl<S, R> State<'_, S, R> {
        self.send_handshake_data(material).await?;

        // 4. wait for the remote response with their own encrypted signature
-        let materials = self.receive_handshake_message::<MaterialExchange>().await?;
+        let (materials, client_protocol) =
+            self.receive_handshake_message::<MaterialExchange>().await?;
+        if client_protocol != self.proposed_protocol_version() {
+            warn!("the client hasn't accepted our proposed protocol version. we suggested {:?} while it returned {client_protocol:?}", self.proposed_protocol_version());
+            // TBD what to do here
+        }

        // 5. verify the received signature using the locally derived keys
        self.verify_remote_key_material(&materials, &init_message.ephemeral_dh)?;
@@ -54,7 +89,7 @@ impl<S, R> State<'_, S, R> {
    pub(crate) async fn perform_gateway_handshake(
        mut self,
        raw_init_message: Vec<u8>,
-    ) -> Result<SharedGatewayKey, HandshakeError>
+    ) -> Result<HandshakeResult, HandshakeError>
    where
        S: Stream<Item = WsItem> + Sink<WsMessage> + Unpin,
    {
@@ -24,13 +24,6 @@ pub struct Initialisation {
    pub initiator_salt: Option<Vec<u8>>,
 }

-impl Initialisation {
-    #[cfg(not(target_arch = "wasm32"))]
-    pub fn is_legacy(&self) -> bool {
-        self.initiator_salt.is_none()
-    }
-}
-
 #[derive(Debug)]
 pub struct MaterialExchange {
    pub signature_ciphertext: Vec<u8>,
@@ -99,8 +92,9 @@ impl HandshakeMessage for Initialisation {
        let identity = ed25519::PublicKey::from_bytes(&bytes[..ed25519::PUBLIC_KEY_LENGTH])
            .map_err(|_| HandshakeError::MalformedRequest)?;

-        // this can only fail if the provided bytes have len different from encryption::PUBLIC_KEY_SIZE
+        // SAFETY: this can only fail if the provided bytes have len different from encryption::PUBLIC_KEY_SIZE
        // which is impossible
+        #[allow(clippy::unwrap_used)]
        let ephemeral_dh =
            x25519::PublicKey::from_bytes(&bytes[ed25519::PUBLIC_KEY_LENGTH..legacy_len]).unwrap();

@@ -194,6 +188,7 @@ impl HandshakeMessage for GatewayMaterialExchange {

        // this can only fail if the provided bytes have len different from PUBLIC_KEY_SIZE
        // which is impossible
+        #[allow(clippy::unwrap_used)]
        let ephemeral_dh =
            x25519::PublicKey::from_bytes(&bytes[..x25519::PUBLIC_KEY_SIZE]).unwrap();
        let materials = MaterialExchange::try_from_bytes(&bytes[x25519::PUBLIC_KEY_SIZE..])?;
@@ -3,7 +3,7 @@

 use self::error::HandshakeError;
 use crate::registration::handshake::state::State;
-use crate::SharedGatewayKey;
+use crate::{GatewayProtocolVersion, SharedGatewayKey};
 use futures::future::BoxFuture;
 use futures::{Sink, Stream};
 use nym_crypto::asymmetric::ed25519;
@@ -34,24 +34,29 @@ pub const KDF_SALT_LENGTH: usize = 16;
 // we do not need to worry about that.

 pub struct GatewayHandshake<'a> {
-    handshake_future: BoxFuture<'a, Result<SharedGatewayKey, HandshakeError>>,
+    handshake_future: BoxFuture<'a, Result<HandshakeResult, HandshakeError>>,
 }

 impl Future for GatewayHandshake<'_> {
-    type Output = Result<SharedGatewayKey, HandshakeError>;
+    type Output = Result<HandshakeResult, HandshakeError>;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        Pin::new(&mut self.handshake_future).poll(cx)
    }
 }

+#[derive(Debug, PartialEq)]
+pub struct HandshakeResult {
+    pub negotiated_protocol: GatewayProtocolVersion,
+    pub derived_key: SharedGatewayKey,
+}
+
 pub fn client_handshake<'a, S, R>(
    rng: &'a mut R,
    ws_stream: &'a mut S,
    identity: &'a ed25519::KeyPair,
    gateway_pubkey: ed25519::PublicKey,
-    expects_credential_usage: bool,
-    derive_aes256_gcm_siv_key: bool,
+    gateway_protocol: Option<GatewayProtocolVersion>,
    #[cfg(not(target_arch = "wasm32"))] shutdown_token: ShutdownToken,
 ) -> GatewayHandshake<'a>
 where
@@ -63,11 +68,10 @@ where
        ws_stream,
        identity,
        Some(gateway_pubkey),
+        gateway_protocol,
        #[cfg(not(target_arch = "wasm32"))]
        shutdown_token,
-    )
-    .with_credential_usage(expects_credential_usage)
-    .with_aes256_gcm_siv_key(derive_aes256_gcm_siv_key);
+    );

    GatewayHandshake {
        handshake_future: Box::pin(state.perform_client_handshake()),
@@ -80,13 +84,21 @@ pub fn gateway_handshake<'a, S, R>(
    ws_stream: &'a mut S,
    identity: &'a ed25519::KeyPair,
    received_init_payload: Vec<u8>,
+    requested_client_protocol: Option<GatewayProtocolVersion>,
    shutdown_token: ShutdownToken,
 ) -> GatewayHandshake<'a>
 where
    S: Stream<Item = WsItem> + Sink<WsMessage> + Unpin + Send + 'a,
    R: CryptoRng + RngCore + Send,
 {
-    let state = State::new(rng, ws_stream, identity, None, shutdown_token);
+    let state = State::new(
+        rng,
+        ws_stream,
+        identity,
+        None,
+        requested_client_protocol,
+        shutdown_token,
+    );
    GatewayHandshake {
        handshake_future: Box::pin(state.perform_gateway_handshake(received_init_payload)),
    }
@@ -113,7 +125,8 @@ DONE(status)
 #[cfg(test)]
 mod tests {
    use super::*;
-    use crate::ClientControlRequest;
+    use crate::{ClientControlRequest, CURRENT_PROTOCOL_VERSION, INITIAL_PROTOCOL_VERSION};
+    use anyhow::{bail, Context};
    use futures::StreamExt;
    use nym_test_utils::helpers::u64_seeded_rng;
    use nym_test_utils::mocks::stream_sink::mock_streams;
@@ -121,10 +134,53 @@ mod tests {
    use tokio::join;
    use tungstenite::Message;

-    #[tokio::test]
-    async fn basic_handshake() -> anyhow::Result<()> {
-        use anyhow::Context as _;
+    trait ClientControlRequestExt {
+        async fn get_handshake_init_data(&mut self) -> anyhow::Result<Vec<u8>> {
+            let ClientControlRequest::RegisterHandshakeInitRequest {
+                protocol_version: _,
+                data,
+            } = self.get_control_request().await?
+            else {
+                bail!("unexpected ClientControlRequest")
+            };
+            Ok(data)
+        }
+        async fn get_control_request(&mut self) -> anyhow::Result<ClientControlRequest>;
+    }

+    impl<T> ClientControlRequestExt for T
+    where
+        T: Stream<Item = WsItem> + Unpin,
+    {
+        async fn get_control_request(&mut self) -> anyhow::Result<ClientControlRequest> {
+            let msg = self
+                .next()
+                .timeboxed()
+                .await
+                .context("timeout")?
+                .context("no message!")??
+                .into_text()?
+                .parse::<ClientControlRequest>()?;
+            Ok(msg)
+        }
+    }
+
+    struct Party<R: 'static, S: 'static> {
+        rng: &'static mut R,
+        keys: &'static mut ed25519::KeyPair,
+        socket: &'static mut S,
+    }
+
+    fn setup() -> (
+        Party<
+            impl CryptoRng + RngCore + Send,
+            impl Stream<Item = WsItem> + Sink<WsMessage> + Unpin,
+        >,
+        Party<
+            impl CryptoRng + RngCore + Send,
+            impl Stream<Item = WsItem> + Sink<WsMessage> + Unpin,
+        >,
+    ) {
        // solve the lifetime issue by just leaking the contents of the boxes
        // which is perfectly fine in test
        let client_rng = u64_seeded_rng(42).leak();
@@ -142,51 +198,139 @@ mod tests {
        let client_ws = client_ws.leak();
        let gateway_ws = gateway_ws.leak();

+        (
+            Party {
+                rng: client_rng,
+                keys: client_keys,
+                socket: client_ws,
+            },
+            Party {
+                rng: gateway_rng,
+                keys: gateway_keys,
+                socket: gateway_ws,
+            },
+        )
+    }
+
+    #[tokio::test]
+    async fn basic_handshake() -> anyhow::Result<()> {
+        let (client, gateway) = setup();
+
        let handshake_client = client_handshake(
-            client_rng,
-            client_ws,
-            client_keys,
-            *gateway_keys.public_key(),
-            false,
-            true,
+            client.rng,
+            client.socket,
+            client.keys,
+            *gateway.keys.public_key(),
+            Some(CURRENT_PROTOCOL_VERSION),
            ShutdownToken::default(),
        );

        let client_fut = handshake_client.spawn_timeboxed();

        // we need to receive the first message so that it could be propagated to the gateway side of the handshake
-        let ClientControlRequest::RegisterHandshakeInitRequest {
-            protocol_version: _,
-            data,
-        } = (gateway_ws.next())
-            .timeboxed()
-            .await
-            .context("timeout")?
-            .context("no message!")??
-            .into_text()?
-            .parse::<ClientControlRequest>()?
-        else {
-            panic!("bad message")
-        };
-
-        let init_msg = data;
+        let init_msg = gateway.socket.get_handshake_init_data().await?;

        let handshake_gateway = gateway_handshake(
-            gateway_rng,
-            gateway_ws,
-            gateway_keys,
+            gateway.rng,
+            gateway.socket,
+            gateway.keys,
            init_msg,
+            Some(CURRENT_PROTOCOL_VERSION),
            ShutdownToken::default(),
        );

        let gateway_fut = handshake_gateway.spawn_timeboxed();
        let (client, gateway) = join!(client_fut, gateway_fut);

-        let client_key = client???;
-        let gateway_key = gateway???;
+        let client_res = client???;
+        let gateway_res = gateway???;

        // ensure the created keys are the same
-        assert_eq!(client_key, gateway_key);
+        assert_eq!(client_res, gateway_res);
+        assert_eq!(client_res.negotiated_protocol, CURRENT_PROTOCOL_VERSION);
+
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn protocol_downgrade() -> anyhow::Result<()> {
+        let (client, gateway) = setup();
+
+        let handshake_client = client_handshake(
+            client.rng,
+            client.socket,
+            client.keys,
+            *gateway.keys.public_key(),
+            Some(CURRENT_PROTOCOL_VERSION + 42),
+            ShutdownToken::default(),
+        );
+
+        let client_fut = handshake_client.spawn_timeboxed();
+        // we need to receive the first message so that it could be propagated to the gateway side of the handshake
+        let init_msg = gateway.socket.get_handshake_init_data().await?;
+
+        let handshake_gateway = gateway_handshake(
+            gateway.rng,
+            gateway.socket,
+            gateway.keys,
+            init_msg,
+            Some(CURRENT_PROTOCOL_VERSION + 42),
+            ShutdownToken::default(),
+        );
+
+        let gateway_fut = handshake_gateway.spawn_timeboxed();
+        let (client, gateway) = join!(client_fut, gateway_fut);
+
+        let client_res = client???;
+        let gateway_res = gateway???;
+
+        // ensure the created keys are the same
+        assert_eq!(client_res, gateway_res);
+
+        // and the protocol got downgraded for both parties
+        assert_eq!(client_res.negotiated_protocol, CURRENT_PROTOCOL_VERSION);
+
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn protocol_upgrade() -> anyhow::Result<()> {
+        let (client, gateway) = setup();
+
+        let handshake_client = client_handshake(
+            client.rng,
+            client.socket,
+            client.keys,
+            *gateway.keys.public_key(),
+            None,
+            ShutdownToken::default(),
+        );
+
+        let client_fut = handshake_client.spawn_timeboxed();
+
+        // we need to receive the first message so that it could be propagated to the gateway side of the handshake
+        let init_msg = gateway.socket.get_handshake_init_data().await?;
+
+        let handshake_gateway = gateway_handshake(
+            gateway.rng,
+            gateway.socket,
+            gateway.keys,
+            init_msg,
+            None,
+            ShutdownToken::default(),
+        );
+
+        let gateway_fut = handshake_gateway.spawn_timeboxed();
+        let (client, gateway) = join!(client_fut, gateway_fut);
+
+        let client_res = client???;
+        let gateway_res = gateway???;
+
+        // ensure the created keys are the same
+        assert_eq!(client_res, gateway_res);
+
+        // and the protocol got upgraded to the first known version
+        assert_eq!(client_res.negotiated_protocol, INITIAL_PROTOCOL_VERSION);

        Ok(())
    }
--- a/Show More
+++ b/Show More