ignore precommits from missing validators

allow conversion from CometBFT block subscription
old validator rewarder with updated cosmrs
2025-06-23 10:46:01 +01:00 · 2025-02-19 14:56:40 +00:00 · 2025-02-19 14:33:37 +00:00 · 2024-09-27 18:23:32 +01:00 · 2024-09-27 18:10:59 +01:00 · 2024-09-27 17:53:55 +01:00
251 changed files with 10389 additions and 3493 deletions
@@ -26,6 +26,7 @@ on:
      - "nym-api/**"
      - "nym-node/**"
      - "nym-outfox/**"
+      - 'nym-data-observatory/**'
      - "nym-validator-rewarder/**"
      - "sdk/rust/nym-sdk/**"
      - "service-providers/**"
@@ -56,7 +57,7 @@ jobs:
          echo $OUTPUT_DIR

      - name: Install Dependencies (Linux)
-        run: sudo apt update && sudo apt install libudev-dev
+        run: sudo apt-get update && sudo apt-get -y install libudev-dev

      - name: Sets env vars for tokio if set in manual dispatch inputs
        run: |
@@ -96,6 +97,7 @@ jobs:
            target/release/nym-socks5-client
            target/release/nym-api
            target/release/nym-network-requester
+            target/release/nym-data-observatory
            target/release/nym-cli
            target/release/nymvisor
            target/release/nym-node
@@ -113,6 +115,7 @@ jobs:
          cp target/release/nym-socks5-client $OUTPUT_DIR
          cp target/release/nym-api $OUTPUT_DIR
          cp target/release/nym-network-requester $OUTPUT_DIR
+          cp target/release/nym-data-observatory $OUTPUT_DIR
          cp target/release/nymvisor $OUTPUT_DIR
          cp target/release/nym-node $OUTPUT_DIR
          cp target/release/nym-cli $OUTPUT_DIR
@@ -16,6 +16,7 @@ on:
      - 'nym-api/**'
      - 'nym-node/**'
      - 'nym-outfox/**'
+      - 'nym-data-observatory/**'
      - 'nym-validator-rewarder/**'
      - 'tools/**'
      - 'wasm/**'
@@ -90,14 +91,6 @@ jobs:
          command: test
          args: --workspace -- --ignored

-      - name: Annotate with clippy checks
-        if: contains(matrix.os, 'ubuntu')
-        uses: actions-rs/clippy-check@v1
-        continue-on-error: true
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          args: --workspace
-
      - name: Clippy
        uses: actions-rs/cargo@v1
        with:
@@ -18,8 +18,8 @@ jobs:

    steps:
    - uses: actions/checkout@v4
-    - uses: EmbarkStudios/cargo-deny-action@v1
+    - uses: EmbarkStudios/cargo-deny-action@v2
      with:
        log-level: warn
        command: check ${{ matrix.checks }}
-        argument: --all-features
+        arguments: --all-features
@@ -0,0 +1,55 @@
+name: Build and upload Network monitor container to harbor.nymte.ch
+on:
+  workflow_dispatch:
+
+env:
+  WORKING_DIRECTORY: "."
+  CONTAINER_NAME: "network-monitor"
+
+jobs:
+  build-container:
+    runs-on: arc-ubuntu-22.04-dind
+    steps:
+      - name: Login to Harbor
+        uses: docker/login-action@v3
+        with:
+          registry: harbor.nymte.ch
+          username: ${{ secrets.HARBOR_ROBOT_USERNAME }}
+          password: ${{ secrets.HARBOR_ROBOT_SECRET }}
+
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Configure git identity
+        run: |
+          git config --global user.email "lawrence@nymtech.net"
+          git config --global user.name "Lawrence Stalder"
+
+      - name: Get version from package.json
+        uses: sergeysova/jq-action@v2
+        id: get_version
+        with:
+          cmd: jq -r '.version' ${{ env.WORKING_DIRECTORY }}/package.json
+
+      - name: Check if tag exists
+        run: |
+          if git rev-parse ${{ steps.get_version.outputs.value }} >/dev/null 2>&1; then
+            echo "Tag ${{ steps.get_version.outputs.value }} already exists"
+          fi
+
+      - name: Remove existing tag if exists
+        run: |
+          if git rev-parse ${{ steps.get_version.outputs.value }} >/dev/null 2>&1; then
+            git push --delete origin ${{ steps.get_version.outputs.value }}
+            git tag -d ${{ steps.get_version.outputs.value }}
+          fi
+
+      - name: Create tag
+        run: |
+          git tag -a ${{ steps.get_version.outputs.value }} -m "Version ${{ steps.get_version.outputs.value }}"
+          git push origin ${{ steps.get_version.outputs.value }}
+
+      - name: BuildAndPushImageOnHarbor
+        run: |
+          docker build -f nym-network-monitor.dockerfile ${{ env.WORKING_DIRECTORY }} -t harbor.nymte.ch/nym/${{ env.CONTAINER_NAME }}:${{ steps.get_version.outputs.value }} -t harbor.nymte.ch/nym/${{ env.CONTAINER_NAME }}:latest
+          docker push harbor.nymte.ch/nym/${{ env.CONTAINER_NAME }} --all-tags
@@ -4,6 +4,82 @@ Post 1.0.0 release, the changelog format is based on [Keep a Changelog](https://

 ## [Unreleased]

+## [2024.11-wedel] (2024-09-23)
+
+- Backport #4894 to fix ci ([#4899])
+- Bugfix/ticketbook false double spending ([#4892])
+- fix: allow updating globally stored signatures ([#4891])
+- [DOCs/operators]: Document changelog for patch/2024.10-caramello ([#4886])
+- [DOCs/operators]: Post release docs updates ([#4874])
+- Bump defguard to github latest version ([#4872])
+- chore: removed completed queued mixnet migration ([#4865])
+- Disable push trigger and add missing paths in ci-build ([#4864])
+- Fix linux conditional in ci-build.yml ([#4863])
+- Remove golang workaround in ci-sdk-wasm ([#4858])
+- Revert runner for ci-docs ([#4855])
+- Move credential verification into common crate ([#4853])
+- Fix test failure in ipr request size ([#4844])
+- Start switching over jobs to arc-ubuntu-20.04 ([#4843])
+- Use ecash credential type for bandwidth value ([#4840])
+- Create nym-repo-setup debian package and nym-vpn meta package ([#4837])
+- Remove serde_crate named import ([#4832])
+- Run cargo autoinherit following last weeks dependabot updates ([#4831])
+- revamped ticketbook serialisation and exposed additional cli methods ([#4827])
+- Expose wireguard details on self described endpoint ([#4825])
+- Remove unused wireguard flag from SDK ([#4823])
+- Add `axum` server to `nym-api` ([#4803])
+- Run cargo-autoinherit for a few new crates ([#4801])
+- Update dependabot ([#4796])
+- Fix clippy for unwrap_or_default ([#4783])
+- Enable dependabot version upgrades for root rust workspace ([#4778])
+- Persist used wireguard private IPs ([#4771])
+- Avoid race on ip and registration structures ([#4766])
+- docs/hotfix ([#4765])
+- chore: remove repetitive words ([#4763])
+- Make gateway latency check generic ([#4759])
+- Remove duplicate stat count for retransmissions ([#4756])
+- Update peer refresh value ([#4754])
+- Remove deprecated mark_as_success and use new disarm ([#4751])
+- Add get_mixnodes_described to validator_client ([#4725])
+- New Network Monitor ([#4610])
+
+[#4899]: https://github.com/nymtech/nym/pull/4899
+[#4892]: https://github.com/nymtech/nym/pull/4892
+[#4891]: https://github.com/nymtech/nym/pull/4891
+[#4886]: https://github.com/nymtech/nym/pull/4886
+[#4874]: https://github.com/nymtech/nym/pull/4874
+[#4872]: https://github.com/nymtech/nym/pull/4872
+[#4865]: https://github.com/nymtech/nym/pull/4865
+[#4864]: https://github.com/nymtech/nym/pull/4864
+[#4863]: https://github.com/nymtech/nym/pull/4863
+[#4858]: https://github.com/nymtech/nym/pull/4858
+[#4855]: https://github.com/nymtech/nym/pull/4855
+[#4853]: https://github.com/nymtech/nym/pull/4853
+[#4844]: https://github.com/nymtech/nym/pull/4844
+[#4843]: https://github.com/nymtech/nym/pull/4843
+[#4840]: https://github.com/nymtech/nym/pull/4840
+[#4837]: https://github.com/nymtech/nym/pull/4837
+[#4832]: https://github.com/nymtech/nym/pull/4832
+[#4831]: https://github.com/nymtech/nym/pull/4831
+[#4827]: https://github.com/nymtech/nym/pull/4827
+[#4825]: https://github.com/nymtech/nym/pull/4825
+[#4823]: https://github.com/nymtech/nym/pull/4823
+[#4803]: https://github.com/nymtech/nym/pull/4803
+[#4801]: https://github.com/nymtech/nym/pull/4801
+[#4796]: https://github.com/nymtech/nym/pull/4796
+[#4783]: https://github.com/nymtech/nym/pull/4783
+[#4778]: https://github.com/nymtech/nym/pull/4778
+[#4771]: https://github.com/nymtech/nym/pull/4771
+[#4766]: https://github.com/nymtech/nym/pull/4766
+[#4765]: https://github.com/nymtech/nym/pull/4765
+[#4763]: https://github.com/nymtech/nym/pull/4763
+[#4759]: https://github.com/nymtech/nym/pull/4759
+[#4756]: https://github.com/nymtech/nym/pull/4756
+[#4754]: https://github.com/nymtech/nym/pull/4754
+[#4751]: https://github.com/nymtech/nym/pull/4751
+[#4725]: https://github.com/nymtech/nym/pull/4725
+[#4610]: https://github.com/nymtech/nym/pull/4610
+
 ## [2024.10-caramello] (2024-09-10)

 - Backport 4844 and 4845 ([#4857])
@@ -81,6 +81,7 @@ members = [
    "common/nyxd-scraper",
    "common/pemstore",
    "common/serde-helpers",
+    "common/service-provider-requests-common",
    "common/socks5-client-core",
    "common/socks5/proxy-helpers",
    "common/socks5/requests",
@@ -102,6 +103,9 @@ members = [
    "mixnode",
    "sdk/lib/socks5-listener",
    "sdk/rust/nym-sdk",
+    "sdk/ffi/shared",
+    "sdk/ffi/go",
+    "sdk/ffi/cpp",
    "service-providers/authenticator",
    "service-providers/common",
    "service-providers/ip-packet-router",
@@ -110,11 +114,13 @@ members = [
    "nym-api",
    "nym-browser-extension/storage",
    "nym-api/nym-api-requests",
+    "nym-data-observatory",
    "nym-node",
    "nym-node/nym-node-http-api",
    "nym-node/nym-node-requests",
    "nym-outfox",
    "nym-validator-rewarder",
+    "tools/echo-server",
    "tools/internal/ssl-inject",
    # "tools/internal/sdk-version-bump",
    "tools/internal/testnet-manager",
@@ -129,6 +135,9 @@ members = [
    "wasm/mix-fetch",
    "wasm/node-tester",
    "wasm/zknym-lib",
+    "tools/internal/testnet-manager",
+    "tools/internal/testnet-manager/dkg-bypass-contract",
+    "tools/echo-server",
 ]

 default-members = [
@@ -138,6 +147,7 @@ default-members = [
    "gateway",
    "mixnode",
    "nym-api",
+    "nym-data-observatory",
    "nym-node",
    "nym-validator-rewarder",
    "service-providers/authenticator",
@@ -152,7 +162,6 @@ exclude = [
    "nym-wallet",
    "nym-vpn/ui/src-tauri",
    "cpu-cycles",
-    "sdk/ffi/cpp",
 ]

 [workspace.package]
@@ -169,7 +178,9 @@ readme = "README.md"
 addr = "0.15.6"
 aes = "0.8.1"
 aes-gcm = "0.10.1"
-anyhow = "1.0.87"
+aes-gcm-siv = "0.11.1"
+aead = "0.5.2"
+anyhow = "1.0.89"
 argon2 = "0.5.0"
 async-trait = "0.1.82"
 axum = "0.7.5"
@@ -198,7 +209,7 @@ clap = "4.5.17"
 clap_complete = "4.5"
 clap_complete_fig = "4.5"
 colored = "2.0"
-comfy-table = "6.0.0"
+comfy-table = "7.1.1"
 console = "0.15.8"
 console-subscriber = "0.1.1"
 console_error_panic_hook = "0.1"
@@ -210,7 +221,8 @@ ctr = "0.9.1"
 cupid = "0.6.1"
 curve25519-dalek = "4.1"
 dashmap = "5.5.3"
-defguard_wireguard_rs = "0.4.2"
+# We want https://github.com/DefGuard/wireguard-rs/pull/64 , but there's no crates.io release being pushed out anymore
+defguard_wireguard_rs = { git = "https://github.com/DefGuard/wireguard-rs.git", rev = "v0.4.7" }
 digest = "0.10.7"
 dirs = "5.0"
 doc-comment = "0.3"
@@ -224,7 +236,7 @@ flate2 = "1.0.33"
 futures = "0.3.28"
 generic-array = "0.14.7"
 getrandom = "0.2.10"
-getset = "0.1.1"
+getset = "0.1.3"
 handlebars = "3.5.5"
 headers = "0.4.0"
 hex = "0.4.3"
@@ -232,10 +244,12 @@ hex-literal = "0.3.3"
 hkdf = "0.12.3"
 hmac = "0.12.1"
 http = "1"
+http-body-util = "0.1"
 httpcodec = "0.2.3"
 humantime = "2.1.0"
 humantime-serde = "1.1.1"
-hyper = "1.3.1"
+hyper = "1.4.1"
+hyper-util = "0.1"
 indicatif = "0.17.8"
 inquire = "0.6.2"
 ip_network = "0.4.1"
@@ -274,7 +288,7 @@ reqwest = { version = "0.12.4", default-features = false }
 rocket = "0.5.0"
 rocket_cors = "0.6.0"
 rocket_okapi = "0.8.0"
-safer-ffi = "0.1.12"
+safer-ffi = "0.1.13"
 schemars = "0.8.21"
 semver = "1.0.23"
 serde = "1.0.210"
@@ -291,7 +305,7 @@ sqlx = "0.6.3"
 strum = "0.26"
 subtle-encoding = "0.5"
 syn = "1"
-sysinfo = "0.30.12"
+sysinfo = "0.30.13"
 tap = "1.0.1"
 tar = "0.4.41"
 tempfile = "3.5.0"
@@ -300,6 +314,7 @@ time = "0.3.30"
 tokio = "1.39"
 tokio-stream = "0.1.16"
 tokio-test = "0.4.4"
+tokio-tun = "0.11.5"
 tokio-tungstenite = { version = "0.20.1" }
 tokio-util = "0.7.12"
 toml = "0.8.14"
@@ -313,7 +328,6 @@ ts-rs = "7.0.0"
 tungstenite = { version = "0.20.1", default-features = false }
 url = "2.5"
 utoipa = "4.2"
-utoipa-rapidoc = "4.0"
 utoipa-swagger-ui = "7.1"
 utoipauto = "0.1"
 uuid = "*"
@@ -334,7 +348,6 @@ group = { version = "0.13.0", default-features = false }
 ff = { version = "0.13.0", default-features = false }

 # cosmwasm-related
-cosmwasm-derive = "=1.4.3"
 cosmwasm-schema = "=1.4.3"
 cosmwasm-std = "=1.4.3"
 # use 0.5.0 as that's the version used by cosmwasm-std 1.4.3
@@ -352,13 +365,10 @@ cw-controllers = { version = "=1.1.0" }
 # cosmrs-related
 bip32 = { version = "0.5.2", default-features = false }

-# temporarily using a fork again (yay.) because we need staking and slashing support (which are already on main but not released)
-# plus response message parsing (which is, as of the time of writing this message, waiting to get merged)
-#cosmrs = { path = "../cosmos-rust-fork/cosmos-rust/cosmrs" }
-cosmrs = { git = "https://github.com/cosmos/cosmos-rust", rev = "4b1332e6d8258ac845cef71589c8d362a669675a" } # unfortuntely we need a fork by yours truly to get the staking support
-tendermint = "0.37.0"                                                                                        # same version as used by cosmrs
-tendermint-rpc = "0.37.0"                                                                                    # same version as used by cosmrs
-prost = { version = "0.12", default-features = false }
+cosmrs = { version = "0.21.1" }
+tendermint = "0.40.0"
+tendermint-rpc = "0.40.0"
+prost = { version = "0.13", default-features = false }

 # wasm-related dependencies
 gloo-utils = "0.2.0"
@@ -1,6 +1,6 @@
 [package]
 name = "nym-client"
-version = "1.1.40"
+version = "1.1.41"
 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.40"
+version = "1.1.41"
 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"
@@ -9,9 +9,24 @@ edition.workspace = true
 license.workspace = true

 [dependencies]
+base64 = { workspace = true }
 bincode = { workspace = true }
 rand = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
+thiserror = { workspace = true }

+nym-credentials-interface = { path = "../credentials-interface" }
+nym-crypto = { path = "../crypto", features = ["asymmetric"] }
+nym-service-provider-requests-common = { path = "../service-provider-requests-common" }
 nym-sphinx = { path = "../nymsphinx" }
 nym-wireguard-types = { path = "../wireguard-types" }
+
+## verify:
+hmac = { workspace = true, optional = true }
+sha2 = { workspace = true, optional = true }
+x25519-dalek = { workspace = true, features = ["static_secrets"] }
+
+[features]
+default = ["verify"]
+# this is moved to a separate feature as we really need clients to import it (especially, *cough*, wasm)
+verify = ["hmac", "sha2"]
@@ -0,0 +1,22 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum Error {
+    #[error("the provided base64-encoded client MAC ('{mac}') was malformed: {source}")]
+    MalformedClientMac {
+        mac: String,
+        #[source]
+        source: base64::DecodeError,
+    },
+
+    #[cfg(feature = "verify")]
+    #[error("failed to verify mac provided by '{client}': {source}")]
+    FailedClientMacVerification {
+        client: String,
+        #[source]
+        source: hmac::digest::MacError,
+    },
+}
@@ -2,8 +2,14 @@
 // SPDX-License-Identifier: Apache-2.0

 pub mod v1;
+pub mod v2;

-pub const CURRENT_VERSION: u8 = 1;
+mod error;
+
+pub use error::Error;
+pub use v2 as latest;
+
+pub const CURRENT_VERSION: u8 = 2;

 fn make_bincode_serializer() -> impl bincode::Options {
    use bincode::Options;
@@ -1,7 +1,13 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+pub mod registration;
 pub mod request;
 pub mod response;

-const VERSION: u8 = 1;
+pub use registration::{ClientMac, GatewayClient, InitMessage, Nonce};
+
+#[cfg(feature = "verify")]
+pub use registration::HmacSha256;
+
+pub const VERSION: u8 = 1;
@@ -0,0 +1,218 @@
+// Copyright 2023-2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::error::Error;
+use base64::{engine::general_purpose, Engine};
+use nym_wireguard_types::PeerPublicKey;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::net::IpAddr;
+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::encryption::PrivateKey;
+#[cfg(feature = "verify")]
+use sha2::Sha256;
+
+pub type PendingRegistrations = HashMap<PeerPublicKey, RegistrationData>;
+pub type PrivateIPs = HashMap<IpAddr, Taken>;
+
+#[cfg(feature = "verify")]
+pub type HmacSha256 = Hmac<Sha256>;
+
+pub type Nonce = u64;
+pub type Taken = Option<SystemTime>;
+
+pub const BANDWIDTH_CAP_PER_DAY: i64 = 1024 * 1024 * 1024; // 1 GB
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+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)]
+pub struct RegistrationData {
+    pub nonce: u64,
+    pub gateway_data: GatewayClient,
+    pub wg_port: u16,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct RegistredData {
+    pub pub_key: PeerPublicKey,
+    pub private_ip: IpAddr,
+    pub wg_port: u16,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct RemainingBandwidthData {
+    pub available_bandwidth: u64,
+    pub suspended: bool,
+}
+
+/// 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)]
+pub struct GatewayClient {
+    /// Base64 encoded x25519 public key
+    pub pub_key: PeerPublicKey,
+
+    /// Assigned private IP
+    pub private_ip: IpAddr,
+
+    /// 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_ip: IpAddr,
+        nonce: u64,
+    ) -> Self {
+        // convert from 1.0 x25519-dalek private key into 2.0 x25519-dalek
+        #[allow(clippy::expect_used)]
+        let static_secret = x25519_dalek::StaticSecret::from(local_secret.to_bytes());
+        let local_public: x25519_dalek::PublicKey = (&static_secret).into();
+
+        let dh = static_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.as_bytes())
+            .expect("x25519 shared secret is always 32 bytes long");
+
+        mac.update(local_public.as_bytes());
+        mac.update(private_ip.to_string().as_bytes());
+        mac.update(&nonce.to_le_bytes());
+
+        GatewayClient {
+            pub_key: PeerPublicKey::new(local_public),
+            private_ip,
+            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> {
+        // convert from 1.0 x25519-dalek private key into 2.0 x25519-dalek
+        #[allow(clippy::expect_used)]
+        let static_secret = x25519_dalek::StaticSecret::from(gateway_key.to_bytes());
+
+        let dh = static_secret.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_ip.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)]
+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 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::encryption;
+
+    #[test]
+    #[cfg(feature = "verify")]
+    fn client_request_roundtrip() {
+        let mut rng = rand::thread_rng();
+
+        let gateway_key_pair = encryption::KeyPair::new(&mut rng);
+        let client_key_pair = encryption::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()),
+            "10.0.0.42".parse().unwrap(),
+            nonce,
+        );
+        assert!(client.verify(gateway_key_pair.private_key(), nonce).is_ok())
+    }
+}
@@ -1,8 +1,9 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+use super::registration::{GatewayClient, InitMessage};
 use nym_sphinx::addressing::Recipient;
-use nym_wireguard_types::{GatewayClient, InitMessage, PeerPublicKey};
+use nym_wireguard_types::PeerPublicKey;
 use serde::{Deserialize, Serialize};

 use crate::make_bincode_serializer;
@@ -82,3 +83,24 @@ pub enum AuthenticatorRequestData {
    Final(GatewayClient),
    QueryBandwidth(PeerPublicKey),
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::str::FromStr;
+
+    #[test]
+    fn check_first_byte_version() {
+        let version = 2;
+        let data = AuthenticatorRequest {
+            version,
+            data: AuthenticatorRequestData::Initial(InitMessage::new(
+                PeerPublicKey::from_str("yvNUDpT5l7W/xDhiu6HkqTHDQwbs/B3J5UrLmORl1EQ=").unwrap(),
+            )),
+            reply_to: Recipient::try_from_base58_string("D1rrpsysCGCYXy9saP8y3kmNpGtJZUXN9SvFoUcqAsM9.9Ssso1ea5NfkbMASdiseDSjTN1fSWda5SgEVjdSN4CvV@GJqd3ZxpXWSNxTfx7B1pPtswpetH4LnJdFeLeuY5KUuN").unwrap(),
+            request_id: 1,
+        };
+        let bytes = data.to_bytes().unwrap();
+        assert_eq!(*bytes.first().unwrap(), version);
+    }
+}
@@ -1,8 +1,8 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

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

 use crate::make_bincode_serializer;
@@ -0,0 +1,174 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+
+use crate::{v1, v2};
+
+impl From<v1::request::AuthenticatorRequest> for v2::request::AuthenticatorRequest {
+    fn from(authenticator_request: v1::request::AuthenticatorRequest) -> Self {
+        Self {
+            protocol: Protocol {
+                version: 2,
+                service_provider_type: ServiceProviderType::Authenticator,
+            },
+            data: authenticator_request.data.into(),
+            reply_to: authenticator_request.reply_to,
+            request_id: authenticator_request.request_id,
+        }
+    }
+}
+
+impl From<v1::request::AuthenticatorRequestData> for v2::request::AuthenticatorRequestData {
+    fn from(authenticator_request_data: v1::request::AuthenticatorRequestData) -> Self {
+        match authenticator_request_data {
+            v1::request::AuthenticatorRequestData::Initial(init_msg) => {
+                v2::request::AuthenticatorRequestData::Initial(init_msg.into())
+            }
+            v1::request::AuthenticatorRequestData::Final(gw_client) => {
+                v2::request::AuthenticatorRequestData::Final(gw_client.into())
+            }
+            v1::request::AuthenticatorRequestData::QueryBandwidth(pub_key) => {
+                v2::request::AuthenticatorRequestData::QueryBandwidth(pub_key)
+            }
+        }
+    }
+}
+
+impl From<v1::registration::InitMessage> for v2::registration::InitMessage {
+    fn from(init_msg: v1::registration::InitMessage) -> Self {
+        Self {
+            pub_key: init_msg.pub_key,
+        }
+    }
+}
+
+impl From<v1::registration::GatewayClient> for Box<v2::registration::FinalMessage> {
+    fn from(gw_client: v1::registration::GatewayClient) -> Self {
+        Box::new(v2::registration::FinalMessage {
+            gateway_client: gw_client.into(),
+            credential: None,
+        })
+    }
+}
+
+impl From<v1::registration::GatewayClient> for v2::registration::GatewayClient {
+    fn from(gw_client: v1::registration::GatewayClient) -> Self {
+        Self {
+            pub_key: gw_client.pub_key,
+            private_ip: gw_client.private_ip,
+            mac: gw_client.mac.into(),
+        }
+    }
+}
+
+impl From<v2::registration::GatewayClient> for v1::registration::GatewayClient {
+    fn from(gw_client: v2::registration::GatewayClient) -> Self {
+        Self {
+            pub_key: gw_client.pub_key,
+            private_ip: gw_client.private_ip,
+            mac: gw_client.mac.into(),
+        }
+    }
+}
+
+impl From<v1::registration::ClientMac> for v2::registration::ClientMac {
+    fn from(mac: v1::registration::ClientMac) -> Self {
+        Self::new(mac.to_vec())
+    }
+}
+
+impl From<v2::registration::ClientMac> for v1::registration::ClientMac {
+    fn from(mac: v2::registration::ClientMac) -> Self {
+        Self::new(mac.to_vec())
+    }
+}
+
+impl From<v2::response::AuthenticatorResponse> for v1::response::AuthenticatorResponse {
+    fn from(authenticator_response: v2::response::AuthenticatorResponse) -> Self {
+        Self {
+            version: authenticator_response.protocol.version,
+            data: authenticator_response.data.into(),
+            reply_to: authenticator_response.reply_to,
+        }
+    }
+}
+
+impl From<v2::response::AuthenticatorResponseData> for v1::response::AuthenticatorResponseData {
+    fn from(authenticator_response_data: v2::response::AuthenticatorResponseData) -> Self {
+        match authenticator_response_data {
+            v2::response::AuthenticatorResponseData::PendingRegistration(
+                pending_registration_response,
+            ) => v1::response::AuthenticatorResponseData::PendingRegistration(
+                pending_registration_response.into(),
+            ),
+            v2::response::AuthenticatorResponseData::Registered(registered_response) => {
+                v1::response::AuthenticatorResponseData::Registered(registered_response.into())
+            }
+            v2::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response,
+            ) => v1::response::AuthenticatorResponseData::RemainingBandwidth(
+                remaining_bandwidth_response.into(),
+            ),
+        }
+    }
+}
+
+impl From<v2::response::PendingRegistrationResponse> for v1::response::PendingRegistrationResponse {
+    fn from(value: v2::response::PendingRegistrationResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply_to: value.reply_to,
+            reply: value.reply.into(),
+        }
+    }
+}
+
+impl From<v2::response::RegisteredResponse> for v1::response::RegisteredResponse {
+    fn from(value: v2::response::RegisteredResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply_to: value.reply_to,
+            reply: value.reply.into(),
+        }
+    }
+}
+
+impl From<v2::response::RemainingBandwidthResponse> for v1::response::RemainingBandwidthResponse {
+    fn from(value: v2::response::RemainingBandwidthResponse) -> Self {
+        Self {
+            request_id: value.request_id,
+            reply_to: value.reply_to,
+            reply: value.reply.map(Into::into),
+        }
+    }
+}
+
+impl From<v2::registration::RegistrationData> for v1::registration::RegistrationData {
+    fn from(value: v2::registration::RegistrationData) -> Self {
+        Self {
+            nonce: value.nonce,
+            gateway_data: value.gateway_data.into(),
+            wg_port: value.wg_port,
+        }
+    }
+}
+
+impl From<v2::registration::RegistredData> for v1::registration::RegistredData {
+    fn from(value: v2::registration::RegistredData) -> Self {
+        Self {
+            pub_key: value.pub_key,
+            private_ip: value.private_ip,
+            wg_port: value.wg_port,
+        }
+    }
+}
+
+impl From<v2::registration::RemainingBandwidthData> for v1::registration::RemainingBandwidthData {
+    fn from(value: v2::registration::RemainingBandwidthData) -> Self {
+        Self {
+            available_bandwidth: value.available_bandwidth as u64,
+            suspended: false,
+        }
+    }
+}
@@ -0,0 +1,9 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+pub mod conversion;
+pub mod registration;
+pub mod request;
+pub mod response;
+
+pub const VERSION: u8 = 2;
@@ -1,9 +1,10 @@
-// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2023-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

 use crate::error::Error;
-use crate::PeerPublicKey;
 use base64::{engine::general_purpose, Engine};
+use nym_credentials_interface::CredentialSpendingData;
+use nym_wireguard_types::PeerPublicKey;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::net::IpAddr;
@@ -29,32 +30,26 @@ pub type Taken = Option<SystemTime>;
 pub const BANDWIDTH_CAP_PER_DAY: u64 = 1024 * 1024 * 1024; // 1 GB

 #[derive(Serialize, Deserialize, Debug, Clone)]
-#[serde(tag = "type", rename_all = "camelCase")]
-#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
-pub enum ClientMessage {
-    Initial(InitMessage),
-    Final(GatewayClient),
-    Query(PeerPublicKey),
-}
-
-#[derive(Serialize, Deserialize, Debug, Clone)]
-#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
 pub struct InitMessage {
    /// Base64 encoded x25519 public key
-    #[cfg_attr(feature = "openapi", schema(value_type = String, format = Byte))]
    pub pub_key: PeerPublicKey,
 }

 impl InitMessage {
-    pub fn pub_key(&self) -> PeerPublicKey {
-        self.pub_key
-    }
-
    pub fn new(pub_key: PeerPublicKey) -> Self {
        InitMessage { pub_key }
    }
 }

+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct FinalMessage {
+    /// Gateway client data
+    pub gateway_client: GatewayClient,
+
+    /// Ecash credential
+    pub credential: Option<CredentialSpendingData>,
+}
+
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct RegistrationData {
    pub nonce: u64,
@@ -71,24 +66,20 @@ pub struct RegistredData {

 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct RemainingBandwidthData {
-    pub available_bandwidth: u64,
-    pub suspended: bool,
+    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)]
-#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
 pub struct GatewayClient {
    /// Base64 encoded x25519 public key
-    #[cfg_attr(feature = "openapi", schema(value_type = String, format = Byte))]
    pub pub_key: PeerPublicKey,

    /// Assigned private IP
    pub private_ip: IpAddr,

    /// Sha256 hmac on the data (alongside the prior nonce)
-    #[cfg_attr(feature = "openapi", schema(value_type = String, format = Byte))]
    pub mac: ClientMac,
 }

@@ -0,0 +1,116 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::registration::{FinalMessage, InitMessage};
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+use nym_sphinx::addressing::Recipient;
+use nym_wireguard_types::PeerPublicKey;
+use serde::{Deserialize, Serialize};
+
+use crate::make_bincode_serializer;
+
+use super::VERSION;
+
+fn generate_random() -> u64 {
+    use rand::RngCore;
+    let mut rng = rand::rngs::OsRng;
+    rng.next_u64()
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AuthenticatorRequest {
+    pub protocol: Protocol,
+    pub data: AuthenticatorRequestData,
+    pub reply_to: Recipient,
+    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, reply_to: Recipient) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: Protocol {
+                    service_provider_type: ServiceProviderType::Authenticator,
+                    version: VERSION,
+                },
+                data: AuthenticatorRequestData::Initial(init_message),
+                reply_to,
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn new_final_request(final_message: FinalMessage, reply_to: Recipient) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: Protocol {
+                    service_provider_type: ServiceProviderType::Authenticator,
+                    version: VERSION,
+                },
+                data: AuthenticatorRequestData::Final(Box::new(final_message)),
+                reply_to,
+                request_id,
+            },
+            request_id,
+        )
+    }
+
+    pub fn new_query_request(peer_public_key: PeerPublicKey, reply_to: Recipient) -> (Self, u64) {
+        let request_id = generate_random();
+        (
+            Self {
+                protocol: Protocol {
+                    service_provider_type: ServiceProviderType::Authenticator,
+                    version: VERSION,
+                },
+                data: AuthenticatorRequestData::QueryBandwidth(peer_public_key),
+                reply_to,
+                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)]
+pub enum AuthenticatorRequestData {
+    Initial(InitMessage),
+    Final(Box<FinalMessage>),
+    QueryBandwidth(PeerPublicKey),
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::str::FromStr;
+
+    #[test]
+    fn check_first_bytes_protocol() {
+        let version = 2;
+        let data = AuthenticatorRequest {
+            protocol: Protocol { version, service_provider_type: ServiceProviderType::Authenticator },
+            data: AuthenticatorRequestData::Initial(InitMessage::new(
+                PeerPublicKey::from_str("yvNUDpT5l7W/xDhiu6HkqTHDQwbs/B3J5UrLmORl1EQ=").unwrap(),
+            )),
+            reply_to: Recipient::try_from_base58_string("D1rrpsysCGCYXy9saP8y3kmNpGtJZUXN9SvFoUcqAsM9.9Ssso1ea5NfkbMASdiseDSjTN1fSWda5SgEVjdSN4CvV@GJqd3ZxpXWSNxTfx7B1pPtswpetH4LnJdFeLeuY5KUuN").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,129 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::registration::{RegistrationData, RegistredData, RemainingBandwidthData};
+use nym_service_provider_requests_common::{Protocol, ServiceProviderType};
+use nym_sphinx::addressing::Recipient;
+use serde::{Deserialize, Serialize};
+
+use crate::make_bincode_serializer;
+
+use super::VERSION;
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AuthenticatorResponse {
+    pub protocol: Protocol,
+    pub data: AuthenticatorResponseData,
+    pub reply_to: Recipient,
+}
+
+impl AuthenticatorResponse {
+    pub fn new_pending_registration_success(
+        registration_data: RegistrationData,
+        request_id: u64,
+        reply_to: Recipient,
+    ) -> Self {
+        Self {
+            protocol: Protocol {
+                service_provider_type: ServiceProviderType::Authenticator,
+                version: VERSION,
+            },
+            data: AuthenticatorResponseData::PendingRegistration(PendingRegistrationResponse {
+                reply: registration_data,
+                reply_to,
+                request_id,
+            }),
+            reply_to,
+        }
+    }
+
+    pub fn new_registered(
+        registred_data: RegistredData,
+        reply_to: Recipient,
+        request_id: u64,
+    ) -> Self {
+        Self {
+            protocol: Protocol {
+                service_provider_type: ServiceProviderType::Authenticator,
+                version: VERSION,
+            },
+            data: AuthenticatorResponseData::Registered(RegisteredResponse {
+                reply: registred_data,
+                reply_to,
+                request_id,
+            }),
+            reply_to,
+        }
+    }
+
+    pub fn new_remaining_bandwidth(
+        remaining_bandwidth_data: Option<RemainingBandwidthData>,
+        reply_to: Recipient,
+        request_id: u64,
+    ) -> Self {
+        Self {
+            protocol: Protocol {
+                service_provider_type: ServiceProviderType::Authenticator,
+                version: VERSION,
+            },
+            data: AuthenticatorResponseData::RemainingBandwidth(RemainingBandwidthResponse {
+                reply: remaining_bandwidth_data,
+                reply_to,
+                request_id,
+            }),
+            reply_to,
+        }
+    }
+
+    pub fn recipient(&self) -> Recipient {
+        self.reply_to
+    }
+
+    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),
+        }
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum AuthenticatorResponseData {
+    PendingRegistration(PendingRegistrationResponse),
+    Registered(RegisteredResponse),
+    RemainingBandwidth(RemainingBandwidthResponse),
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct PendingRegistrationResponse {
+    pub request_id: u64,
+    pub reply_to: Recipient,
+    pub reply: RegistrationData,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct RegisteredResponse {
+    pub request_id: u64,
+    pub reply_to: Recipient,
+    pub reply: RegistredData,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct RemainingBandwidthResponse {
+    pub request_id: u64,
+    pub reply_to: Recipient,
+    pub reply: Option<RemainingBandwidthData>,
+}
@@ -18,7 +18,7 @@ nym-ecash-time = { path = "../ecash-time" }
 nym-credential-storage = { path = "../credential-storage" }
 nym-credentials = { path = "../credentials" }
 nym-credentials-interface = { path = "../credentials-interface" }
-nym-crypto = { path = "../crypto", features = ["rand", "asymmetric", "symmetric", "aes", "hashing"] }
+nym-crypto = { path = "../crypto", features = ["rand", "asymmetric", "stream_cipher", "aes", "hashing"] }
 nym-network-defaults = { path = "../network-defaults" }
 nym-validator-client = { path = "../client-libs/validator-client", default-features = false }
 nym-ecash-contract-common = { path = "../cosmwasm-smart-contracts/ecash-contract" }
@@ -8,14 +8,14 @@ license = { workspace = true }
 repository = { workspace = true }

 [dependencies]
-const-str = { workspace = true }
 clap = { workspace = true, features = ["derive"], optional = true }
 clap_complete = { workspace = true, optional = true }
 clap_complete_fig = { workspace = true, optional = true }
+const-str = { workspace = true }
 log = { workspace = true }
 pretty_env_logger = { workspace = true }
-semver = "0.11"
 schemars = { workspace = true, features = ["preserve_order"], optional = true }
+semver.workspace = true
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true, optional = true }

@@ -1,9 +1,10 @@
 // Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use semver::SemVerError;
 pub use semver::Version;

+/// Checks if the version is minor version compatible.
+///
 /// Checks whether given `version` is compatible with a given semantic version requirement `req`
 /// according to major-minor semver rules. The semantic version requirement can be passed as a full,
 /// concrete version number, because that's what we'll have in our Cargo.toml files (e.g. 0.3.2).
@@ -22,7 +23,7 @@ pub fn is_minor_version_compatible(version: &str, req: &str) -> bool {
    expected_version.major == req_version.major && expected_version.minor == req_version.minor
 }

-pub fn parse_version(raw_version: &str) -> Result<Version, SemVerError> {
+pub fn parse_version(raw_version: &str) -> Result<Version, semver::Error> {
    Version::parse(raw_version)
 }

@@ -14,7 +14,7 @@ base64 = { workspace = true }
 bs58 = { workspace = true }
 cfg-if = { workspace = true }
 clap = { workspace = true, optional = true }
-comfy-table = { version = "7.1.1", optional = true }
+comfy-table = { workspace = true, optional = true }
 futures = { workspace = true }
 humantime-serde = { workspace = true }
 log = { workspace = true }
@@ -59,19 +59,19 @@ nym-ecash-time = { path = "../ecash-time" }

 ### For serving prometheus metrics
 [target."cfg(not(target_arch = \"wasm32\"))".dependencies.hyper]
-version = "1"
+workspace = true
 features = ["server", "http1"]

 [target."cfg(not(target_arch = \"wasm32\"))".dependencies.http-body-util]
-version = "0.1"
+workspace = true

 [target."cfg(not(target_arch = \"wasm32\"))".dependencies.hyper-util]
-version = "0.1"
+workspace = true
 features = ["tokio"]
 ###

 [target."cfg(not(target_arch = \"wasm32\"))".dependencies.tokio-stream]
-version = "0.1.16"
+workspace = true
 features = ["time"]

 [target."cfg(not(target_arch = \"wasm32\"))".dependencies.tokio]
@@ -110,7 +110,7 @@ path = "../wasm/utils"
 features = ["websocket"]

 [target."cfg(target_arch = \"wasm32\")".dependencies.time]
-version = "0.3.17"
+workspace = true
 features = ["wasm-bindgen"]

 [dev-dependencies]
@@ -0,0 +1,13 @@
+/*
+ * Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+-- make aes128 key column nullable and add aes256 column
+ALTER TABLE remote_gateway_details RENAME COLUMN derived_aes128_ctr_blake3_hmac_keys_bs58 TO derived_aes128_ctr_blake3_hmac_keys_bs58_old;
+ALTER TABLE remote_gateway_details ADD COLUMN derived_aes128_ctr_blake3_hmac_keys_bs58 TEXT;
+ALTER TABLE remote_gateway_details ADD COLUMN derived_aes256_gcm_siv_key BLOB;
+
+UPDATE remote_gateway_details SET derived_aes128_ctr_blake3_hmac_keys_bs58 = derived_aes128_ctr_blake3_hmac_keys_bs58_old;
+
+ALTER TABLE remote_gateway_details DROP COLUMN derived_aes128_ctr_blake3_hmac_keys_bs58_old;
@@ -155,11 +155,12 @@ impl StorageManager {
    ) -> Result<(), sqlx::Error> {
        sqlx::query!(
            r#"
-                INSERT INTO remote_gateway_details(gateway_id_bs58, derived_aes128_ctr_blake3_hmac_keys_bs58, gateway_owner_address, gateway_listener) 
-                VALUES (?, ?, ?, ?)
+                INSERT INTO remote_gateway_details(gateway_id_bs58, derived_aes128_ctr_blake3_hmac_keys_bs58, derived_aes256_gcm_siv_key, gateway_owner_address, gateway_listener)
+                VALUES (?, ?, ?, ?, ?)
            "#,
            remote.gateway_id_bs58,
            remote.derived_aes128_ctr_blake3_hmac_keys_bs58,
+            remote.derived_aes256_gcm_siv_key,
            remote.gateway_owner_address,
            remote.gateway_listener,
        )
@@ -168,6 +169,30 @@ impl StorageManager {
        Ok(())
    }

+    pub(crate) async fn update_remote_gateway_key(
+        &self,
+        gateway_id_bs58: &str,
+        derived_aes128_ctr_blake3_hmac_keys_bs58: Option<&str>,
+        derived_aes256_gcm_siv_key: Option<&[u8]>,
+    ) -> Result<(), sqlx::Error> {
+        sqlx::query!(
+            r#"
+                UPDATE remote_gateway_details
+                SET
+                    derived_aes128_ctr_blake3_hmac_keys_bs58 = ?,
+                    derived_aes256_gcm_siv_key = ?
+                WHERE gateway_id_bs58 = ?
+            "#,
+            derived_aes128_ctr_blake3_hmac_keys_bs58,
+            derived_aes256_gcm_siv_key,
+            gateway_id_bs58
+        )
+        .execute(&self.connection_pool)
+        .await?;
+
+        Ok(())
+    }
+
    pub(crate) async fn remove_remote_gateway_details(
        &self,
        gateway_id: &str,
@@ -7,7 +7,8 @@ use crate::{
 };
 use async_trait::async_trait;
 use manager::StorageManager;
-use nym_crypto::asymmetric::identity::PublicKey;
+use nym_crypto::asymmetric::ed25519;
+use nym_gateway_requests::SharedSymmetricKey;
 use std::path::Path;

 pub mod error;
@@ -67,7 +68,7 @@ impl GatewaysDetailsStore for OnDiskGatewaysDetails {
        Ok(registered)
    }

-    async fn all_gateways_identities(&self) -> Result<Vec<PublicKey>, Self::StorageError> {
+    async fn all_gateways_identities(&self) -> Result<Vec<ed25519::PublicKey>, Self::StorageError> {
        Ok(self
            .manager
            .registered_gateways()
@@ -132,6 +133,21 @@ impl GatewaysDetailsStore for OnDiskGatewaysDetails {
        Ok(())
    }

+    async fn upgrade_stored_remote_gateway_key(
+        &self,
+        gateway_id: ed25519::PublicKey,
+        updated_key: &SharedSymmetricKey,
+    ) -> Result<(), Self::StorageError> {
+        self.manager
+            .update_remote_gateway_key(
+                &gateway_id.to_base58_string(),
+                None,
+                Some(updated_key.as_bytes()),
+            )
+            .await?;
+        Ok(())
+    }
+
    // ideally all of those should be run under a storage tx to ensure storage consistency,
    // but at that point it's fine
    async fn remove_gateway_details(&self, gateway_id: &str) -> Result<(), Self::StorageError> {
@@ -2,8 +2,10 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::types::{ActiveGateway, GatewayRegistration};
-use crate::{BadGateway, GatewaysDetailsStore};
+use crate::{BadGateway, GatewayDetails, GatewaysDetailsStore};
 use async_trait::async_trait;
+use nym_crypto::asymmetric::ed25519::PublicKey;
+use nym_gateway_requests::{SharedGatewayKey, SharedSymmetricKey};
 use std::collections::HashMap;
 use std::sync::Arc;
 use thiserror::Error;
@@ -34,10 +36,6 @@ struct InMemStorageInner {
 impl GatewaysDetailsStore for InMemGatewaysDetails {
    type StorageError = InMemStorageError;

-    async fn has_gateway_details(&self, gateway_id: &str) -> Result<bool, Self::StorageError> {
-        Ok(self.inner.read().await.gateways.contains_key(gateway_id))
-    }
-
    async fn active_gateway(&self) -> Result<ActiveGateway, Self::StorageError> {
        let guard = self.inner.read().await;

@@ -68,6 +66,10 @@ impl GatewaysDetailsStore for InMemGatewaysDetails {
        Ok(self.inner.read().await.gateways.values().cloned().collect())
    }

+    async fn has_gateway_details(&self, gateway_id: &str) -> Result<bool, Self::StorageError> {
+        Ok(self.inner.read().await.gateways.contains_key(gateway_id))
+    }
+
    async fn load_gateway_details(
        &self,
        gateway_id: &str,
@@ -94,6 +96,29 @@ impl GatewaysDetailsStore for InMemGatewaysDetails {
        Ok(())
    }

+    async fn upgrade_stored_remote_gateway_key(
+        &self,
+        gateway_id: PublicKey,
+        updated_key: &SharedSymmetricKey,
+    ) -> Result<(), Self::StorageError> {
+        let mut guard = self.inner.write().await;
+
+        #[allow(clippy::unwrap_used)]
+        if let Some(target) = guard.gateways.get_mut(&gateway_id.to_string()) {
+            let GatewayDetails::Remote(details) = &mut target.details else {
+                return Ok(());
+            };
+            assert_eq!(Arc::strong_count(&details.shared_key), 1);
+
+            // eh. that's nasty, but it's only ever used for ephemeral clients so should be fine for now...
+            details.shared_key = Arc::new(SharedGatewayKey::Current(
+                SharedSymmetricKey::try_from_bytes(updated_key.as_bytes()).unwrap(),
+            ))
+        }
+
+        Ok(())
+    }
+
    async fn remove_gateway_details(&self, gateway_id: &str) -> Result<(), Self::StorageError> {
        let mut guard = self.inner.write().await;
        if let Some(active) = guard.active_gateway.as_ref() {
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use nym_crypto::asymmetric::identity::Ed25519RecoveryError;
-use nym_gateway_requests::registration::handshake::shared_key::SharedKeyConversionError;
+use nym_gateway_requests::shared_key::SharedKeyConversionError;
 use thiserror::Error;

 #[derive(Debug, Error)]
@@ -36,6 +36,9 @@ pub enum BadGateway {
        source: SharedKeyConversionError,
    },

+    #[error("could not find any valid shared keys for gateway {gateway_id}")]
+    MissingSharedKey { gateway_id: String },
+
    #[error(
        "the listening address of gateway {gateway_id} ({raw_listener}) is malformed: {source}"
    )]
@@ -5,6 +5,8 @@
 #![warn(clippy::unwrap_used)]

 use async_trait::async_trait;
+use nym_crypto::asymmetric::identity;
+use nym_gateway_requests::SharedSymmetricKey;
 use std::error::Error;

 pub mod backend;
@@ -18,7 +20,6 @@ pub use error::BadGateway;

 #[cfg(all(not(target_arch = "wasm32"), feature = "fs-gateways-storage"))]
 pub use backend::fs_backend::{error::StorageError, OnDiskGatewaysDetails};
-use nym_crypto::asymmetric::identity;

 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
 #[cfg_attr(not(target_arch = "wasm32"), async_trait)]
@@ -61,6 +62,12 @@ pub trait GatewaysDetailsStore {
        details: &GatewayRegistration,
    ) -> Result<(), Self::StorageError>;

+    async fn upgrade_stored_remote_gateway_key(
+        &self,
+        gateway_id: identity::PublicKey,
+        updated_key: &SharedSymmetricKey,
+    ) -> Result<(), Self::StorageError>;
+
    /// Remove given gateway details from the underlying store.
    async fn remove_gateway_details(&self, gateway_id: &str) -> Result<(), Self::StorageError>;
 }
@@ -4,9 +4,10 @@
 use crate::BadGateway;
 use cosmrs::AccountId;
 use nym_crypto::asymmetric::identity;
-use nym_gateway_requests::registration::handshake::SharedKeys;
+use nym_gateway_requests::shared_key::{LegacySharedKeys, SharedGatewayKey, SharedSymmetricKey};
 use serde::{Deserialize, Serialize};
 use std::fmt::{Display, Formatter};
+use std::ops::Deref;
 use std::str::FromStr;
 use std::sync::Arc;
 use time::OffsetDateTime;
@@ -64,13 +65,13 @@ impl From<GatewayDetails> for GatewayRegistration {
 impl GatewayDetails {
    pub fn new_remote(
        gateway_id: identity::PublicKey,
-        derived_aes128_ctr_blake3_hmac_keys: Arc<SharedKeys>,
+        shared_key: Arc<SharedGatewayKey>,
        gateway_owner_address: Option<AccountId>,
        gateway_listener: Url,
    ) -> Self {
        GatewayDetails::Remote(RemoteGatewayDetails {
            gateway_id,
-            derived_aes128_ctr_blake3_hmac_keys,
+            shared_key,
            gateway_owner_address,
            gateway_listener,
        })
@@ -87,9 +88,9 @@ impl GatewayDetails {
        }
    }

-    pub fn shared_key(&self) -> Option<&SharedKeys> {
+    pub fn shared_key(&self) -> Option<&SharedGatewayKey> {
        match self {
-            GatewayDetails::Remote(details) => Some(&details.derived_aes128_ctr_blake3_hmac_keys),
+            GatewayDetails::Remote(details) => Some(&details.shared_key),
            GatewayDetails::Custom(_) => None,
        }
    }
@@ -167,7 +168,8 @@ pub struct RegisteredGateway {
 #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))]
 pub struct RawRemoteGatewayDetails {
    pub gateway_id_bs58: String,
-    pub derived_aes128_ctr_blake3_hmac_keys_bs58: String,
+    pub derived_aes128_ctr_blake3_hmac_keys_bs58: Option<String>,
+    pub derived_aes256_gcm_siv_key: Option<Vec<u8>>,
    pub gateway_owner_address: Option<String>,
    pub gateway_listener: String,
 }
@@ -184,13 +186,35 @@ impl TryFrom<RawRemoteGatewayDetails> for RemoteGatewayDetails {
                }
            })?;

-        let derived_aes128_ctr_blake3_hmac_keys = Arc::new(
-            SharedKeys::try_from_base58_string(&value.derived_aes128_ctr_blake3_hmac_keys_bs58)
-                .map_err(|source| BadGateway::MalformedSharedKeys {
-                    gateway_id: value.gateway_id_bs58.clone(),
-                    source,
-                })?,
-        );
+        let shared_key =
+            match (
+                &value.derived_aes256_gcm_siv_key,
+                &value.derived_aes128_ctr_blake3_hmac_keys_bs58,
+            ) {
+                (None, None) => {
+                    return Err(BadGateway::MissingSharedKey {
+                        gateway_id: value.gateway_id_bs58.clone(),
+                    })
+                }
+                (Some(aes256gcm_siv), _) => {
+                    let current_key =
+                        SharedSymmetricKey::try_from_bytes(aes256gcm_siv).map_err(|source| {
+                            BadGateway::MalformedSharedKeys {
+                                gateway_id: value.gateway_id_bs58.clone(),
+                                source,
+                            }
+                        })?;
+                    SharedGatewayKey::Current(current_key)
+                }
+                (None, Some(aes128ctr_hmac)) => {
+                    let legacy_key = LegacySharedKeys::try_from_base58_string(aes128ctr_hmac)
+                        .map_err(|source| BadGateway::MalformedSharedKeys {
+                            gateway_id: value.gateway_id_bs58.clone(),
+                            source,
+                        })?;
+                    SharedGatewayKey::Legacy(legacy_key)
+                }
+            };

        let gateway_owner_address = value
            .gateway_owner_address
@@ -216,7 +240,7 @@ impl TryFrom<RawRemoteGatewayDetails> for RemoteGatewayDetails {

        Ok(RemoteGatewayDetails {
            gateway_id,
-            derived_aes128_ctr_blake3_hmac_keys,
+            shared_key: Arc::new(shared_key),
            gateway_owner_address,
            gateway_listener,
        })
@@ -225,11 +249,16 @@ impl TryFrom<RawRemoteGatewayDetails> for RemoteGatewayDetails {

 impl<'a> From<&'a RemoteGatewayDetails> for RawRemoteGatewayDetails {
    fn from(value: &'a RemoteGatewayDetails) -> Self {
+        let (derived_aes128_ctr_blake3_hmac_keys_bs58, derived_aes256_gcm_siv_key) =
+            match value.shared_key.deref() {
+                SharedGatewayKey::Current(key) => (None, Some(key.to_bytes())),
+                SharedGatewayKey::Legacy(key) => (Some(key.to_base58_string()), None),
+            };
+
        RawRemoteGatewayDetails {
            gateway_id_bs58: value.gateway_id.to_base58_string(),
-            derived_aes128_ctr_blake3_hmac_keys_bs58: value
-                .derived_aes128_ctr_blake3_hmac_keys
-                .to_base58_string(),
+            derived_aes128_ctr_blake3_hmac_keys_bs58,
+            derived_aes256_gcm_siv_key,
            gateway_owner_address: value.gateway_owner_address.as_ref().map(|o| o.to_string()),
            gateway_listener: value.gateway_listener.to_string(),
        }
@@ -240,9 +269,7 @@ impl<'a> From<&'a RemoteGatewayDetails> for RawRemoteGatewayDetails {
 pub struct RemoteGatewayDetails {
    pub gateway_id: identity::PublicKey,

-    // note: `SharedKeys` implement ZeroizeOnDrop, meaning when `RemoteGatewayDetails` is dropped,
-    // the keys will be zeroized
-    pub derived_aes128_ctr_blake3_hmac_keys: Arc<SharedKeys>,
+    pub shared_key: Arc<SharedGatewayKey>,

    pub gateway_owner_address: Option<AccountId>,

@@ -354,12 +354,14 @@ where
        config: &Config,
        initialisation_result: InitialisationResult,
        bandwidth_controller: Option<BandwidthController<C, S::CredentialStore>>,
+        details_store: &S::GatewaysDetailsStore,
        packet_router: PacketRouter,
        shutdown: TaskClient,
    ) -> Result<GatewayClient<C, S::CredentialStore>, ClientCoreError>
    where
        <S::KeyStore as KeyStore>::StorageError: Send + Sync + 'static,
        <S::CredentialStore as CredentialStorage>::StorageError: Send + Sync + 'static,
+        <S::GatewaysDetailsStore as GatewaysDetailsStore>::StorageError: Sync + Send,
    {
        let managed_keys = initialisation_result.client_keys;
        let GatewayDetails::Remote(details) = initialisation_result.gateway_registration.details
@@ -387,23 +389,57 @@ where
                        ),
                    cfg,
                    managed_keys.identity_keypair(),
-                    Some(details.derived_aes128_ctr_blake3_hmac_keys),
+                    Some(details.shared_key),
                    packet_router,
                    bandwidth_controller,
                    shutdown,
                )
            };

-        gateway_client
-            .authenticate_and_start()
+        let gateway_failure = |err| {
+            log::error!("Could not authenticate and start up the gateway connection - {err}");
+            ClientCoreError::GatewayClientError {
+                gateway_id: details.gateway_id.to_base58_string(),
+                source: err,
+            }
+        };
+
+        // the gateway client startup procedure is slightly more complicated now
+        // we need to:
+        // - perform handshake (reg or auth)
+        // - check for key upgrade
+        // - maybe perform another upgrade handshake
+        // - check for bandwidth
+        // - start background tasks
+        let auth_res = gateway_client
+            .perform_initial_authentication()
            .await
-            .map_err(|err| {
-                log::error!("Could not authenticate and start up the gateway connection - {err}");
-                ClientCoreError::GatewayClientError {
-                    gateway_id: details.gateway_id.to_base58_string(),
-                    source: err,
-                }
-            })?;
+            .map_err(gateway_failure)?;
+
+        if auth_res.requires_key_upgrade {
+            // drop the shared_key arc because we don't need it and we can't hold it for the purposes of upgrade
+            drop(auth_res);
+
+            let updated_key = gateway_client
+                .upgrade_key_authenticated()
+                .await
+                .map_err(gateway_failure)?;
+
+            details_store
+                .upgrade_stored_remote_gateway_key(gateway_client.gateway_identity(), &updated_key)
+                .await.map_err(|err| {
+                    error!("failed to store upgraded gateway key! this connection might be forever broken now: {err}");
+                    ClientCoreError::GatewaysDetailsStoreError { source: Box::new(err) }
+            })?
+        }
+
+        gateway_client
+            .claim_initial_bandwidth()
+            .await
+            .map_err(gateway_failure)?;
+        gateway_client
+            .start_listening_for_mixnet_messages()
+            .map_err(gateway_failure)?;

        Ok(gateway_client)
    }
@@ -413,12 +449,14 @@ where
        config: &Config,
        initialisation_result: InitialisationResult,
        bandwidth_controller: Option<BandwidthController<C, S::CredentialStore>>,
+        details_store: &S::GatewaysDetailsStore,
        packet_router: PacketRouter,
        mut shutdown: TaskClient,
    ) -> Result<Box<dyn GatewayTransceiver + Send>, ClientCoreError>
    where
        <S::KeyStore as KeyStore>::StorageError: Send + Sync + 'static,
        <S::CredentialStore as CredentialStorage>::StorageError: Send + Sync + 'static,
+        <S::GatewaysDetailsStore as GatewaysDetailsStore>::StorageError: Sync + Send,
    {
        // if we have setup custom gateway sender and persisted details agree with it, return it
        if let Some(mut custom_gateway_transceiver) = custom_gateway_transceiver {
@@ -429,7 +467,7 @@ where
            {
                Err(ClientCoreError::CustomGatewaySelectionExpected)
            } else {
-                // and make sure to invalidate the task client so we wouldn't cause premature shutdown
+                // and make sure to invalidate the task client, so we wouldn't cause premature shutdown
                shutdown.disarm();
                custom_gateway_transceiver.set_packet_router(packet_router)?;
                Ok(custom_gateway_transceiver)
@@ -441,6 +479,7 @@ where
            config,
            initialisation_result,
            bandwidth_controller,
+            details_store,
            packet_router,
            shutdown,
        )
@@ -630,7 +669,8 @@ where
        )
        .await?;

-        let (reply_storage_backend, credential_store) = self.client_store.into_runtime_stores();
+        let (reply_storage_backend, credential_store, details_store) =
+            self.client_store.into_runtime_stores();

        // channels for inter-component communication
        // TODO: make the channels be internally created by the relevant components
@@ -705,6 +745,7 @@ where
            self.config,
            init_res,
            bandwidth_controller,
+            &details_store,
            gateway_packet_router,
            shutdown.fork("gateway_transceiver"),
        )
@@ -13,7 +13,7 @@ pub mod v1_1_33 {
    use nym_client_core_gateways_storage::{
        CustomGatewayDetails, GatewayDetails, GatewayRegistration, RemoteGatewayDetails,
    };
-    use nym_gateway_requests::registration::handshake::SharedKeys;
+    use nym_gateway_requests::shared_key::LegacySharedKeys;
    use serde::{Deserialize, Serialize};
    use sha2::{digest::Digest, Sha256};
    use std::ops::Deref;
@@ -58,7 +58,7 @@ pub mod v1_1_33 {
    }

    impl PersistedGatewayConfig {
-        fn verify(&self, shared_key: &SharedKeys) -> bool {
+        fn verify(&self, shared_key: &LegacySharedKeys) -> bool {
            let key_bytes = Zeroizing::new(shared_key.to_bytes());

            let mut key_hasher = Sha256::new();
@@ -74,7 +74,7 @@ pub mod v1_1_33 {
        gateway_id: String,
    }

-    fn load_shared_key<P: AsRef<Path>>(path: P) -> Result<SharedKeys, ClientCoreError> {
+    fn load_shared_key<P: AsRef<Path>>(path: P) -> Result<LegacySharedKeys, ClientCoreError> {
        // the shared key was a simple pem file
        Ok(nym_pemstore::load_key(path)?)
    }
@@ -83,7 +83,7 @@ pub mod v1_1_33 {
        gateway_id: String,
        gateway_owner: String,
        gateway_listener: String,
-        gateway_shared_key: SharedKeys,
+        gateway_shared_key: LegacySharedKeys,
    ) -> Result<GatewayDetails, ClientCoreError> {
        Ok(GatewayDetails::Remote(RemoteGatewayDetails {
            gateway_id: gateway_id
@@ -91,7 +91,7 @@ pub mod v1_1_33 {
                .map_err(|err| ClientCoreError::UpgradeFailure {
                    message: format!("the stored gateway id was malformed: {err}"),
                })?,
-            derived_aes128_ctr_blake3_hmac_keys: Arc::new(gateway_shared_key),
+            shared_key: Arc::new(gateway_shared_key.into()),
            gateway_owner_address: Some(gateway_owner.parse().map_err(|err| {
                ClientCoreError::UpgradeFailure {
                    message: format!("the stored gateway owner address was malformed: {err}"),
@@ -49,7 +49,13 @@ pub trait MixnetClientStorage {
    type CredentialStore: CredentialStorage;
    type GatewaysDetailsStore: GatewaysDetailsStore;

-    fn into_runtime_stores(self) -> (Self::ReplyStore, Self::CredentialStore);
+    fn into_runtime_stores(
+        self,
+    ) -> (
+        Self::ReplyStore,
+        Self::CredentialStore,
+        Self::GatewaysDetailsStore,
+    );

    fn key_store(&self) -> &Self::KeyStore;
    fn reply_store(&self) -> &Self::ReplyStore;
@@ -77,8 +83,18 @@ impl MixnetClientStorage for Ephemeral {
    type CredentialStore = EphemeralCredentialStorage;
    type GatewaysDetailsStore = InMemGatewaysDetails;

-    fn into_runtime_stores(self) -> (Self::ReplyStore, Self::CredentialStore) {
-        (self.reply_store, self.credential_store)
+    fn into_runtime_stores(
+        self,
+    ) -> (
+        Self::ReplyStore,
+        Self::CredentialStore,
+        Self::GatewaysDetailsStore,
+    ) {
+        (
+            self.reply_store,
+            self.credential_store,
+            self.gateway_details_store,
+        )
    }

    fn key_store(&self) -> &Self::KeyStore {
@@ -168,8 +184,18 @@ impl MixnetClientStorage for OnDiskPersistent {
    type CredentialStore = PersistentCredentialStorage;
    type GatewaysDetailsStore = OnDiskGatewaysDetails;

-    fn into_runtime_stores(self) -> (Self::ReplyStore, Self::CredentialStore) {
-        (self.reply_store, self.credential_store)
+    fn into_runtime_stores(
+        self,
+    ) -> (
+        Self::ReplyStore,
+        Self::CredentialStore,
+        Self::GatewaysDetailsStore,
+    ) {
+        (
+            self.reply_store,
+            self.credential_store,
+            self.gateway_details_store,
+        )
    }

    fn key_store(&self) -> &Self::KeyStore {
@@ -3,7 +3,7 @@

 use crate::client::key_manager::persistence::KeyStore;
 use nym_crypto::asymmetric::{encryption, identity};
-use nym_gateway_requests::registration::handshake::SharedKeys;
+use nym_gateway_requests::shared_key::{LegacySharedKeys, SharedGatewayKey, SharedSymmetricKey};
 use nym_sphinx::acknowledgements::AckKey;
 use rand::{CryptoRng, RngCore};
 use std::sync::Arc;
@@ -84,5 +84,7 @@ fn _assert_keys_zeroize_on_drop() {
    _assert_zeroize_on_drop::<identity::KeyPair>();
    _assert_zeroize_on_drop::<encryption::KeyPair>();
    _assert_zeroize_on_drop::<AckKey>();
-    _assert_zeroize_on_drop::<SharedKeys>();
+    _assert_zeroize_on_drop::<LegacySharedKeys>();
+    _assert_zeroize_on_drop::<SharedSymmetricKey>();
+    _assert_zeroize_on_drop::<SharedGatewayKey>();
 }
@@ -102,6 +102,7 @@ impl TopologyRefresher {
            .current_topology()
            .await
            .ok_or(NymTopologyError::EmptyNetworkTopology)?;
+
        if !topology.gateway_exists(gateway) {
            return Err(NymTopologyError::NonExistentGatewayError {
                identity_key: gateway.to_base58_string(),
@@ -214,6 +214,11 @@ pub enum ClientCoreError {

    #[error("this client has already registered with gateway {gateway_id}")]
    AlreadyRegistered { gateway_id: String },
+
+    #[error(
+        "fresh registration with gateway {gateway_id} somehow requires an additional key upgrade!"
+    )]
+    UnexpectedKeyUpgrade { gateway_id: String },
 }

 /// Set of messages that the client can send to listeners via the task manager
@@ -320,7 +320,7 @@ pub(super) async fn register_with_gateway(
            source: err,
        }
    })?;
-    let shared_keys = gateway_client
+    let auth_response = gateway_client
        .perform_initial_authentication()
        .await
        .map_err(|err| {
@@ -330,8 +330,17 @@ pub(super) async fn register_with_gateway(
                source: err,
            }
        })?;
+
+    // this should NEVER happen, if it did, it means the function was misused,
+    // because for any fresh **registration**, the derived key is always up to date
+    if auth_response.requires_key_upgrade {
+        return Err(ClientCoreError::UnexpectedKeyUpgrade {
+            gateway_id: gateway_id.to_base58_string(),
+        });
+    }
+
    Ok(RegistrationResult {
-        shared_keys,
+        shared_keys: auth_response.initial_shared_key,
        authenticated_ephemeral_client: gateway_client,
    })
 }
@@ -11,7 +11,7 @@ use nym_client_core_gateways_storage::{
 };
 use nym_crypto::asymmetric::identity;
 use nym_gateway_client::client::InitGatewayClient;
-use nym_gateway_requests::registration::handshake::SharedKeys;
+use nym_gateway_requests::shared_key::SharedGatewayKey;
 use nym_sphinx::addressing::clients::Recipient;
 use nym_topology::gateway;
 use nym_validator_client::client::IdentityKey;
@@ -104,7 +104,7 @@ impl SelectedGateway {
 /// - shared keys derived between ourselves and the node
 /// - an authenticated handle of an ephemeral handle created for the purposes of registration
 pub struct RegistrationResult {
-    pub shared_keys: Arc<SharedKeys>,
+    pub shared_keys: Arc<SharedGatewayKey>,
    pub authenticated_ephemeral_client: InitGatewayClient,
 }

@@ -11,13 +11,14 @@ license.workspace = true
 # TODO: (for this and other crates), similarly to 'tokio', import only required "futures" modules rather than
 # the entire crate
 futures = { workspace = true }
-log = { workspace = true }
+tracing = { workspace = true }
 thiserror = { workspace = true }
 url = { workspace = true }
 rand = { workspace = true }
 tokio = { workspace = true, features = ["macros"] }
 si-scale = { workspace = true }
 time.workspace = true
+zeroize.workspace = true

 # internal
 nym-bandwidth-controller = { path = "../../bandwidth-controller" }
@@ -43,7 +44,7 @@ workspace = true
 features = ["macros", "rt", "net", "sync", "time"]

 [target."cfg(not(target_arch = \"wasm32\"))".dependencies.tokio-stream]
-version = "0.1.16"
+workspace = true
 features = ["net", "sync", "time"]

 [target."cfg(not(target_arch = \"wasm32\"))".dependencies.tokio-tungstenite]
@@ -2,21 +2,37 @@
 // SPDX-License-Identifier: Apache-2.0

 use si_scale::helpers::bibytes2;
-use std::sync::atomic::{AtomicI64, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicI64, Ordering};
 use std::sync::Arc;
 use std::time::Duration;
 use time::OffsetDateTime;

-#[derive(Clone, Default)]
+pub(crate) struct BandwidthClaimGuard {
+    inner: Arc<ClientBandwidthInner>,
+}
+
+impl Drop for BandwidthClaimGuard {
+    fn drop(&mut self) {
+        let old = self.inner.claiming_more.swap(false, Ordering::SeqCst);
+        assert!(
+            old,
+            "critical failure: there were multiple BandwidthClaimGuard existing"
+        )
+    }
+}
+
+#[derive(Clone)]
 pub struct ClientBandwidth {
    inner: Arc<ClientBandwidthInner>,
 }

-#[derive(Default)]
 struct ClientBandwidthInner {
    /// the actual bandwidth amount (in bytes) available
    available: AtomicI64,

+    /// flag to indicate whether this client is currently in the process of claiming additional bandwidth
+    claiming_more: AtomicBool,
+
    /// defines the timestamp when the bandwidth information has been logged to the logs stream
    last_logged_ts: AtomicI64,

@@ -29,11 +45,28 @@ impl ClientBandwidth {
        ClientBandwidth {
            inner: Arc::new(ClientBandwidthInner {
                available: AtomicI64::new(0),
+                claiming_more: AtomicBool::new(false),
                last_logged_ts: AtomicI64::new(0),
                last_updated_ts: AtomicI64::new(0),
            }),
        }
    }
+
+    pub(crate) fn begin_bandwidth_claim(&self) -> Option<BandwidthClaimGuard> {
+        if self
+            .inner
+            .claiming_more
+            .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)
+            .is_ok()
+        {
+            Some(BandwidthClaimGuard {
+                inner: self.inner.clone(),
+            })
+        } else {
+            None
+        }
+    }
+
    pub(crate) fn remaining(&self) -> i64 {
        self.inner.available.load(Ordering::Acquire)
    }
@@ -53,9 +86,9 @@ impl ClientBandwidth {
        let remaining_bi2 = bibytes2(remaining as f64);

        if remaining < 0 {
-            log::warn!("OUT OF BANDWIDTH. remaining: {remaining_bi2}");
+            tracing::warn!("OUT OF BANDWIDTH. remaining: {remaining_bi2}");
        } else {
-            log::info!("remaining bandwidth: {remaining_bi2}");
+            tracing::info!("remaining bandwidth: {remaining_bi2}");
        }

        self.inner
@@ -1,5 +1,6 @@
 // Copyright 2021-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
+
 use crate::bandwidth::ClientBandwidth;
 use crate::client::config::GatewayClientConfig;
 use crate::error::GatewayClientError;
@@ -11,24 +12,24 @@ use crate::socket_state::{ws_fd, PartiallyDelegatedHandle, SocketState};
 use crate::traits::GatewayPacketRouter;
 use crate::{cleanup_socket_message, try_decrypt_binary_message};
 use futures::{SinkExt, StreamExt};
-use log::*;
 use nym_bandwidth_controller::{BandwidthController, BandwidthStatusMessage};
 use nym_credential_storage::ephemeral_storage::EphemeralStorage as EphemeralCredentialStorage;
 use nym_credential_storage::storage::Storage as CredentialStorage;
 use nym_credentials::CredentialSpendingData;
 use nym_crypto::asymmetric::identity;
-use nym_gateway_requests::authentication::encrypted_address::EncryptedAddressBytes;
-use nym_gateway_requests::iv::IV;
-use nym_gateway_requests::registration::handshake::{client_handshake, SharedKeys};
+use nym_gateway_requests::registration::handshake::client_handshake;
 use nym_gateway_requests::{
-    BinaryRequest, ClientControlRequest, ServerResponse, CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION,
-    CURRENT_PROTOCOL_VERSION,
+    BinaryRequest, ClientControlRequest, ClientRequest, SensitiveServerResponse, ServerResponse,
+    SharedGatewayKey, SharedSymmetricKey, AES_GCM_SIV_PROTOCOL_VERSION,
+    CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION, CURRENT_PROTOCOL_VERSION,
 };
 use nym_sphinx::forwarding::packet::MixPacket;
 use nym_task::TaskClient;
 use nym_validator_client::nyxd::contract_traits::DkgQueryClient;
 use rand::rngs::OsRng;
 use std::sync::Arc;
+use tracing::instrument;
+use tracing::*;
 use tungstenite::protocol::Message;
 use url::Url;

@@ -45,6 +46,7 @@ use std::os::raw::c_int as RawFd;
 use wasm_utils::websocket::JSWebsocket;
 #[cfg(target_arch = "wasm32")]
 use wasmtimer::tokio::sleep;
+use zeroize::Zeroizing;

 pub mod config;

@@ -71,6 +73,13 @@ impl GatewayConfig {
    }
 }

+#[must_use]
+#[derive(Debug)]
+pub struct AuthenticationResponse {
+    pub initial_shared_key: Arc<SharedGatewayKey>,
+    pub requires_key_upgrade: bool,
+}
+
 // TODO: this should be refactored into a state machine that keeps track of its authentication state
 pub struct GatewayClient<C, St = EphemeralCredentialStorage> {
    pub cfg: GatewayClientConfig,
@@ -80,7 +89,7 @@ pub struct GatewayClient<C, St = EphemeralCredentialStorage> {
    gateway_address: String,
    gateway_identity: identity::PublicKey,
    local_identity: Arc<identity::KeyPair>,
-    shared_key: Option<Arc<SharedKeys>>,
+    shared_key: Option<Arc<SharedGatewayKey>>,
    connection: SocketState,
    packet_router: PacketRouter,
    bandwidth_controller: Option<BandwidthController<C, St>>,
@@ -98,7 +107,7 @@ impl<C, St> GatewayClient<C, St> {
        gateway_config: GatewayConfig,
        local_identity: Arc<identity::KeyPair>,
        // TODO: make it mandatory. if you don't want to pass it, use `new_init`
-        shared_key: Option<Arc<SharedKeys>>,
+        shared_key: Option<Arc<SharedGatewayKey>>,
        packet_router: PacketRouter,
        bandwidth_controller: Option<BandwidthController<C, St>>,
        task_client: TaskClient,
@@ -293,7 +302,7 @@ impl<C, St> GatewayClient<C, St> {
    // as we need to be able to write the request and read the subsequent response
    async fn send_websocket_message(
        &mut self,
-        msg: Message,
+        msg: impl Into<Message>,
    ) -> Result<ServerResponse, GatewayClientError> {
        let should_restart_mixnet_listener = if self.connection.is_partially_delegated() {
            self.recover_socket_connection().await?;
@@ -307,7 +316,7 @@ impl<C, St> GatewayClient<C, St> {
            SocketState::NotConnected => return Err(GatewayClientError::ConnectionNotEstablished),
            _ => return Err(GatewayClientError::ConnectionInInvalidState),
        };
-        conn.send(msg).await?;
+        conn.send(msg.into()).await?;
        let response = self.read_control_response().await;

        if should_restart_mixnet_listener {
@@ -398,13 +407,19 @@ impl<C, St> GatewayClient<C, St> {
        }
    }

-    async fn register(&mut self) -> Result<(), GatewayClientError> {
+    async fn register(
+        &mut self,
+        derive_aes256_gcm_siv_key: bool,
+    ) -> Result<(), GatewayClientError> {
        if !self.connection.is_established() {
            return Err(GatewayClientError::ConnectionNotEstablished);
        }

        debug_assert!(self.connection.is_available());
-        log::debug!("Registering gateway");
+        log::debug!(
+            "registering with gateway. using legacy key derivation: {}",
+            !derive_aes256_gcm_siv_key
+        );

        // it's fine to instantiate it here as it's only used once (during authentication or registration)
        // and putting it into the GatewayClient struct would be a hassle
@@ -417,13 +432,15 @@ impl<C, St> GatewayClient<C, St> {
                self.local_identity.as_ref(),
                self.gateway_identity,
                self.cfg.bandwidth.require_tickets,
+                derive_aes256_gcm_siv_key,
                #[cfg(not(target_arch = "wasm32"))]
                self.task_client.clone(),
            )
            .await
            .map_err(GatewayClientError::RegistrationFailure),
-            _ => unreachable!(),
+            _ => return Err(GatewayClientError::ConnectionInInvalidState),
        }?;
+
        let (authentication_status, gateway_protocol) = match self.read_control_response().await? {
            ServerResponse::Register {
                protocol_version,
@@ -432,7 +449,7 @@ impl<C, St> GatewayClient<C, St> {
            ServerResponse::Error { message } => {
                return Err(GatewayClientError::GatewayError(message))
            }
-            _ => return Err(GatewayClientError::UnexpectedResponse),
+            other => return Err(GatewayClientError::UnexpectedResponse { name: other.name() }),
        };

        self.check_gateway_protocol(gateway_protocol)?;
@@ -448,41 +465,93 @@ impl<C, St> GatewayClient<C, St> {
        Ok(())
    }

-    async fn authenticate(
+    pub async fn upgrade_key_authenticated(
        &mut self,
-        shared_key: Option<SharedKeys>,
-    ) -> Result<(), GatewayClientError> {
-        if shared_key.is_none() && self.shared_key.is_none() {
-            return Err(GatewayClientError::NoSharedKeyAvailable);
-        }
+    ) -> Result<Zeroizing<SharedSymmetricKey>, GatewayClientError> {
+        info!("*** STARTING AES128CTR-HMAC KEY UPGRADE INTO AES256GCM-SIV***");
+
        if !self.connection.is_established() {
            return Err(GatewayClientError::ConnectionNotEstablished);
        }
-        log::debug!("Authenticating with gateway");

-        // it's fine to instantiate it here as it's only used once (during authentication or registration)
-        // and putting it into the GatewayClient struct would be a hassle
-        let mut rng = OsRng;
+        if !self.authenticated {
+            return Err(GatewayClientError::NotAuthenticated);
+        }
+
+        let Some(shared_key) = self.shared_key.as_ref() else {
+            return Err(GatewayClientError::NoSharedKeyAvailable);
+        };
+
+        if !shared_key.is_legacy() {
+            return Err(GatewayClientError::KeyAlreadyUpgraded);
+        }
+
+        // make sure we have the only reference, so we could safely swap it
+        if Arc::strong_count(shared_key) != 1 {
+            return Err(GatewayClientError::KeyAlreadyInUse);
+        }
+
+        assert!(shared_key.is_legacy());
+        let legacy_key = shared_key.unwrap_legacy();
+        let (updated_key, hkdf_salt) = legacy_key.upgrade();
+        let derived_key_digest = updated_key.digest();
+
+        let upgrade_request = ClientRequest::UpgradeKey {
+            hkdf_salt,
+            derived_key_digest,
+        }
+        .encrypt(legacy_key)?;
+
+        info!("sending upgrade request and awaiting the acknowledgement back");
+        let (ciphertext, nonce) = match self.send_websocket_message(upgrade_request).await? {
+            ServerResponse::EncryptedResponse { ciphertext, nonce } => (ciphertext, nonce),
+            ServerResponse::Error { message } => {
+                return Err(GatewayClientError::GatewayError(message))
+            }
+            other => return Err(GatewayClientError::UnexpectedResponse { name: other.name() }),
+        };
+
+        // attempt to decrypt it using NEW key
+        let Ok(response) = SensitiveServerResponse::decrypt(&ciphertext, &nonce, &updated_key)
+        else {
+            return Err(GatewayClientError::FatalKeyUpgradeFailure);
+        };
+
+        match response {
+            SensitiveServerResponse::KeyUpgradeAck { .. } => {
+                info!("received key upgrade acknowledgement")
+            }
+            _ => return Err(GatewayClientError::FatalKeyUpgradeFailure),
+        }
+
+        // perform in memory swap and make a copy for updating storage
+        let zeroizing_updated_key = updated_key.zeroizing_clone();
+        self.shared_key = Some(Arc::new(updated_key.into()));
+
+        Ok(zeroizing_updated_key)
+    }
+
+    async fn authenticate(&mut self) -> Result<(), GatewayClientError> {
+        let Some(shared_key) = self.shared_key.as_ref() else {
+            return Err(GatewayClientError::NoSharedKeyAvailable);
+        };
+
+        if !self.connection.is_established() {
+            return Err(GatewayClientError::ConnectionNotEstablished);
+        }
+        debug!("authenticating with gateway");

-        // because of the previous check one of the unwraps MUST succeed
-        let shared_key = shared_key
-            .as_ref()
-            .unwrap_or_else(|| self.shared_key.as_ref().unwrap());
-        let iv = IV::new_random(&mut rng);
        let self_address = self
            .local_identity
            .as_ref()
            .public_key()
            .derive_destination_address();
-        let encrypted_address = EncryptedAddressBytes::new(&self_address, shared_key, &iv);

        let msg = ClientControlRequest::new_authenticate(
            self_address,
-            encrypted_address,
-            iv,
+            shared_key,
            self.cfg.bandwidth.require_tickets,
-        )
-        .into();
+        )?;

        match self.send_websocket_message(msg).await? {
            ServerResponse::Authenticate {
@@ -496,39 +565,101 @@ impl<C, St> GatewayClient<C, St> {

                self.negotiated_protocol = protocol_version;
                log::debug!("authenticated: {status}, bandwidth remaining: {bandwidth_remaining}");
+
                self.task_client.send_status_msg(Box::new(
                    BandwidthStatusMessage::RemainingBandwidth(bandwidth_remaining),
                ));
                Ok(())
            }
            ServerResponse::Error { message } => Err(GatewayClientError::GatewayError(message)),
-            _ => Err(GatewayClientError::UnexpectedResponse),
+            other => Err(GatewayClientError::UnexpectedResponse { name: other.name() }),
        }
    }

    /// Helper method to either call register or authenticate based on self.shared_key value
+    #[instrument(skip_all,
+        fields(
+            gateway = %self.gateway_identity,
+            gateway_address = %self.gateway_address
+        )
+    )]
    pub async fn perform_initial_authentication(
        &mut self,
-    ) -> Result<Arc<SharedKeys>, GatewayClientError> {
+    ) -> Result<AuthenticationResponse, GatewayClientError> {
+        if !self.connection.is_established() {
+            self.establish_connection().await?;
+        }
+
+        // 1. check gateway's protocol version
+        let supports_aes_gcm_siv = match self.get_gateway_protocol().await {
+            Ok(protocol) => protocol >= AES_GCM_SIV_PROTOCOL_VERSION,
+            Err(_) => {
+                // if we failed to send the request, it means the gateway is running the old binary,
+                // so it has reset our connection - we have to reconnect
+                self.establish_connection().await?;
+                false
+            }
+        };
+
+        if !supports_aes_gcm_siv {
+            warn!("this gateway is on an old version that doesn't support AES256-GCM-SIV");
+        }
+
        if self.authenticated {
            debug!("Already authenticated");
            return if let Some(shared_key) = &self.shared_key {
-                Ok(Arc::clone(shared_key))
+                Ok(AuthenticationResponse {
+                    initial_shared_key: Arc::clone(shared_key),
+                    requires_key_upgrade: shared_key.is_legacy() && supports_aes_gcm_siv,
+                })
            } else {
                Err(GatewayClientError::AuthenticationFailureWithPreexistingSharedKey)
            };
        }

        if self.shared_key.is_some() {
-            self.authenticate(None).await?;
+            self.authenticate().await?;
+
+            if self.authenticated {
+                // if we are authenticated it means we MUST have an associated shared_key
+                let shared_key = self.shared_key.as_ref().unwrap();
+
+                let requires_key_upgrade = shared_key.is_legacy() && supports_aes_gcm_siv;
+
+                Ok(AuthenticationResponse {
+                    initial_shared_key: Arc::clone(shared_key),
+                    requires_key_upgrade,
+                })
+            } else {
+                Err(GatewayClientError::AuthenticationFailure)
+            }
        } else {
-            self.register().await?;
+            self.register(supports_aes_gcm_siv).await?;
+
+            // if registration didn't return an error, we MUST have an associated shared key
+            let shared_key = self.shared_key.as_ref().unwrap();
+
+            // we're always registering with the highest supported protocol,
+            // so no upgrades are required
+            Ok(AuthenticationResponse {
+                initial_shared_key: Arc::clone(shared_key),
+                requires_key_upgrade: false,
+            })
        }
-        if self.authenticated {
-            // if we are authenticated it means we MUST have an associated shared_key
-            Ok(Arc::clone(self.shared_key.as_ref().unwrap()))
-        } else {
-            Err(GatewayClientError::AuthenticationFailure)
+    }
+
+    pub async fn get_gateway_protocol(&mut self) -> Result<u8, GatewayClientError> {
+        if !self.connection.is_established() {
+            return Err(GatewayClientError::ConnectionNotEstablished);
+        }
+
+        match self
+            .send_websocket_message(ClientControlRequest::SupportedProtocol {})
+            .await?
+        {
+            ServerResponse::SupportedProtocol { version } => Ok(version),
+            ServerResponse::Error { message } => Err(GatewayClientError::GatewayError(message)),
+            other => Err(GatewayClientError::UnexpectedResponse { name: other.name() }),
        }
    }

@@ -536,22 +667,17 @@ impl<C, St> GatewayClient<C, St> {
        &mut self,
        credential: CredentialSpendingData,
    ) -> Result<(), GatewayClientError> {
-        let mut rng = OsRng;
-        let iv = IV::new_random(&mut rng);
-
        let msg = ClientControlRequest::new_enc_ecash_credential(
            credential,
            self.shared_key.as_ref().unwrap(),
-            iv,
-        )
-        .into();
+        )?;
        let bandwidth_remaining = match self.send_websocket_message(msg).await? {
            ServerResponse::Bandwidth { available_total } => Ok(available_total),
            ServerResponse::Error { message } => Err(GatewayClientError::GatewayError(message)),
            ServerResponse::TypedError { error } => {
                Err(GatewayClientError::TypedGatewayError(error))
            }
-            _ => Err(GatewayClientError::UnexpectedResponse),
+            other => Err(GatewayClientError::UnexpectedResponse { name: other.name() }),
        }?;

        // TODO: create tracing span
@@ -562,11 +688,11 @@ impl<C, St> GatewayClient<C, St> {
    }

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

        info!("managed to claim testnet bandwidth");
@@ -598,6 +724,11 @@ impl<C, St> GatewayClient<C, St> {
            return Err(GatewayClientError::NoBandwidthControllerAvailable);
        }

+        let Some(_claim_guard) = self.bandwidth.begin_bandwidth_claim() else {
+            debug!("there's already an existing bandwidth claim ongoing");
+            return Ok(());
+        };
+
        warn!("Not enough bandwidth. Trying to get more bandwidth, this might take a while");
        if !self.cfg.bandwidth.require_tickets {
            info!("The client is running in disabled credentials mode - attempting to claim bandwidth without a credential");
@@ -665,10 +796,10 @@ impl<C, St> GatewayClient<C, St> {
            return Err(GatewayClientError::ConnectionNotEstablished);
        }

-        let messages: Vec<_> = packets
+        let messages: Result<Vec<_>, _> = packets
            .into_iter()
            .map(|mix_packet| {
-                BinaryRequest::new_forward_request(mix_packet).into_ws_message(
+                BinaryRequest::ForwardSphinx { packet: mix_packet }.into_ws_message(
                    self.shared_key
                        .as_ref()
                        .expect("no shared key present even though we're authenticated!"),
@@ -677,7 +808,7 @@ impl<C, St> GatewayClient<C, St> {
            .collect();

        if let Err(err) = self
-            .batch_send_websocket_messages_without_response(messages)
+            .batch_send_websocket_messages_without_response(messages?)
            .await
        {
            if err.is_closed_connection() && self.cfg.connection.should_reconnect_on_failure {
@@ -741,11 +872,11 @@ impl<C, St> GatewayClient<C, St> {
        }
        // note: into_ws_message encrypts the requests and adds a MAC on it. Perhaps it should
        // be more explicit in the naming?
-        let msg = BinaryRequest::new_forward_request(mix_packet).into_ws_message(
+        let msg = BinaryRequest::ForwardSphinx { packet: mix_packet }.into_ws_message(
            self.shared_key
                .as_ref()
                .expect("no shared key present even though we're authenticated!"),
-        );
+        )?;
        self.send_with_reconnection_on_failure(msg).await
    }

@@ -805,8 +936,8 @@ impl<C, St> GatewayClient<C, St> {
            self.establish_connection().await?;
        }

-        // TODO: the name of this method is very deceiving
-        self.perform_initial_authentication().await?;
+        // if we're reconnecting, because we lost connection, we need to re-authenticate the connection
+        self.authenticate().await?;

        // this call is NON-blocking
        self.start_listening_for_mixnet_messages()?;
@@ -820,16 +951,16 @@ impl<C, St> GatewayClient<C, St> {
        Ok(())
    }

-    pub async fn authenticate_and_start(&mut self) -> Result<Arc<SharedKeys>, GatewayClientError>
+    pub async fn claim_initial_bandwidth(&mut self) -> Result<(), GatewayClientError>
    where
        C: DkgQueryClient + Send + Sync,
        St: CredentialStorage,
        <St as CredentialStorage>::StorageError: Send + Sync + 'static,
    {
-        if !self.connection.is_established() {
-            self.establish_connection().await?;
+        if !self.authenticated {
+            return Err(GatewayClientError::NotAuthenticated);
        }
-        let shared_key = self.perform_initial_authentication().await?;
+
        let bandwidth_remaining = self.bandwidth.remaining();
        if bandwidth_remaining < self.cfg.bandwidth.remaining_bandwidth_threshold {
            self.cfg
@@ -838,6 +969,20 @@ impl<C, St> GatewayClient<C, St> {
            info!("Claiming more bandwidth with existing credentials. Stop the process now if you don't want that to happen.");
            self.claim_bandwidth().await?;
        }
+        Ok(())
+    }
+
+    #[deprecated(note = "this method does not deal with upgraded keys for legacy clients")]
+    pub async fn authenticate_and_start(
+        &mut self,
+    ) -> Result<AuthenticationResponse, GatewayClientError>
+    where
+        C: DkgQueryClient + Send + Sync,
+        St: CredentialStorage,
+        <St as CredentialStorage>::StorageError: Send + Sync + 'static,
+    {
+        let shared_key = self.perform_initial_authentication().await?;
+        self.claim_initial_bandwidth().await?;

        // this call is NON-blocking
        self.start_listening_for_mixnet_messages()?;
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0

 use nym_gateway_requests::registration::handshake::error::HandshakeError;
-use nym_gateway_requests::SimpleGatewayRequestsError;
+use nym_gateway_requests::{GatewayRequestsError, SimpleGatewayRequestsError};
 use std::io;
 use thiserror::Error;
 use tungstenite::Error as WsError;
@@ -21,9 +21,21 @@ pub enum GatewayClientError {
    #[error("gateway returned an error response: {0}")]
    TypedGatewayError(SimpleGatewayRequestsError),

+    #[error("request error: {0}")]
+    RequestError(#[from] GatewayRequestsError),
+
    #[error("There was a network error: {0}")]
    NetworkError(#[from] WsError),

+    #[error("failed to upgrade our shared key - the gateway sent malformed response")]
+    FatalKeyUpgradeFailure,
+
+    #[error("the current key is already up to date! there's no need to upgrade it")]
+    KeyAlreadyUpgraded,
+
+    #[error("can't perform key upgrade as the key is already being used elsewhere")]
+    KeyAlreadyInUse,
+
    #[cfg(target_arch = "wasm32")]
    #[error("There was a network error: {0}")]
    NetworkErrorWasm(#[from] JsError),
@@ -73,8 +85,8 @@ pub enum GatewayClientError {
        cutoff_bi2: String,
    },

-    #[error("Received an unexpected response")]
-    UnexpectedResponse,
+    #[error("received an unexpected response of type {name}")]
+    UnexpectedResponse { name: String },

    #[error("Connection is in an invalid state - please send a bug report")]
    ConnectionInInvalidState,
@@ -2,12 +2,14 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::error::GatewayClientError;
-use log::warn;
 use nym_gateway_requests::BinaryResponse;
+use tracing::{error, warn};
 use tungstenite::{protocol::Message, Error as WsError};

 pub use client::{config::GatewayClientConfig, GatewayClient, GatewayConfig};
-pub use nym_gateway_requests::registration::handshake::SharedKeys;
+pub use nym_gateway_requests::shared_key::{
+    LegacySharedKeys, SharedGatewayKey, SharedSymmetricKey,
+};
 pub use packet_router::{
    AcknowledgementReceiver, AcknowledgementSender, MixnetMessageReceiver, MixnetMessageSender,
    PacketRouter,
@@ -45,11 +47,15 @@ pub(crate) fn cleanup_socket_messages(

 pub(crate) fn try_decrypt_binary_message(
    bin_msg: Vec<u8>,
-    shared_keys: &SharedKeys,
+    shared_keys: &SharedGatewayKey,
 ) -> Option<Vec<u8>> {
    match BinaryResponse::try_from_encrypted_tagged_bytes(bin_msg, shared_keys) {
        Ok(bin_response) => match bin_response {
-            BinaryResponse::PushedMixMessage(plaintext) => Some(plaintext),
+            BinaryResponse::PushedMixMessage { message } => Some(message),
+            _ => {
+                error!("received unhandled binary response");
+                None
+            }
        },
        Err(err) => {
            warn!("message received from the gateway was malformed! - {err}",);
@@ -44,7 +44,7 @@ impl PacketRouter {
            // having already been dropped
            if self.shutdown.is_shutdown_poll() || self.shutdown.is_dummy() {
                // This should ideally not happen, but it's ok
-                log::warn!("Failed to send mixnet messages due to receiver task shutdown");
+                tracing::warn!("Failed to send mixnet messages due to receiver task shutdown");
                return Err(GatewayClientError::ShutdownInProgress);
            }
            // This should never happen during ordinary operation the way it's currently used.
@@ -60,7 +60,7 @@ impl PacketRouter {
            // having already been dropped
            if self.shutdown.is_shutdown_poll() || self.shutdown.is_dummy() {
                // This should ideally not happen, but it's ok
-                log::warn!("Failed to send acks due to receiver task shutdown");
+                tracing::warn!("Failed to send acks due to receiver task shutdown");
                return Err(GatewayClientError::ShutdownInProgress);
            }
            // This should never happen during ordinary operation the way it's currently used.
@@ -9,15 +9,15 @@ use crate::{cleanup_socket_messages, try_decrypt_binary_message};
 use futures::channel::oneshot;
 use futures::stream::{SplitSink, SplitStream};
 use futures::{SinkExt, StreamExt};
-use log::*;
-use nym_gateway_requests::registration::handshake::SharedKeys;
+use nym_gateway_requests::shared_key::SharedGatewayKey;
 use nym_gateway_requests::{ServerResponse, SimpleGatewayRequestsError};
 use nym_task::TaskClient;
+use si_scale::helpers::bibytes2;
 use std::os::raw::c_int as RawFd;
 use std::sync::Arc;
+use tracing::*;
 use tungstenite::{protocol::Message, Error as WsError};

-use si_scale::helpers::bibytes2;
 #[cfg(unix)]
 use std::os::fd::AsRawFd;
 #[cfg(not(target_arch = "wasm32"))]
@@ -62,7 +62,7 @@ pub(crate) struct PartiallyDelegatedHandle {

 struct PartiallyDelegatedRouter {
    packet_router: PacketRouter,
-    shared_key: Arc<SharedKeys>,
+    shared_key: Arc<SharedGatewayKey>,
    client_bandwidth: ClientBandwidth,

    stream_return: SplitStreamSender,
@@ -72,7 +72,7 @@ struct PartiallyDelegatedRouter {
 impl PartiallyDelegatedRouter {
    fn new(
        packet_router: PacketRouter,
-        shared_key: Arc<SharedKeys>,
+        shared_key: Arc<SharedGatewayKey>,
        client_bandwidth: ClientBandwidth,
        stream_return: SplitStreamSender,
        stream_return_requester: oneshot::Receiver<()>,
@@ -247,7 +247,7 @@ impl PartiallyDelegatedHandle {
    pub(crate) fn split_and_listen_for_mixnet_messages(
        conn: WsConn,
        packet_router: PacketRouter,
-        shared_key: Arc<SharedKeys>,
+        shared_key: Arc<SharedGatewayKey>,
        client_bandwidth: ClientBandwidth,
        shutdown: TaskClient,
    ) -> Self {
@@ -1,9 +1,9 @@
 // Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use log::{error, trace, warn};
 use nym_sphinx::addressing::nodes::MAX_NODE_ADDRESS_UNPADDED_LEN;
 use nym_sphinx::params::PacketSize;
+use tracing::{error, trace, warn};

 pub trait GatewayPacketRouter {
    type Error: std::error::Error;
@@ -20,11 +20,13 @@ nym-coconut-bandwidth-contract-common = { path = "../../cosmwasm-smart-contracts
 nym-ecash-contract-common = { path = "../../cosmwasm-smart-contracts/ecash-contract" }
 nym-multisig-contract-common = { path = "../../cosmwasm-smart-contracts/multisig-contract" }
 nym-group-contract-common = { path = "../../cosmwasm-smart-contracts/group-contract" }
+nym-serde-helpers = { path = "../../serde-helpers", features = ["hex", "base64"] }
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
 nym-http-api-client = { path = "../../../common/http-api-client" }
 thiserror = { workspace = true }
 log = { workspace = true }
+tracing = { workspace = true }
 url = { workspace = true, features = ["serde"] }
 tokio = { workspace = true, features = ["sync", "time"] }
 time = { workspace = true, features = ["formatting"] }
@@ -5,7 +5,7 @@ use crate::nyxd;
 use crate::nyxd::coin::Coin;
 use crate::nyxd::cosmwasm_client::helpers::{create_pagination, next_page_key};
 use crate::nyxd::cosmwasm_client::types::{
-    Account, CodeDetails, Contract, ContractCodeId, SequenceResponse, SimulateResponse,
+    Account, CodeDetails, Contract, ContractCodeId, Model, SequenceResponse, SimulateResponse,
 };
 use crate::nyxd::error::NyxdError;
 use crate::nyxd::Query;
@@ -21,15 +21,14 @@ use cosmrs::proto::cosmos::tx::v1beta1::{
    SimulateRequest, SimulateResponse as ProtoSimulateResponse,
 };
 use cosmrs::proto::cosmwasm::wasm::v1::{
-    QueryCodeRequest, QueryCodeResponse, QueryCodesRequest, QueryCodesResponse,
-    QueryContractHistoryRequest, QueryContractHistoryResponse, QueryContractInfoRequest,
-    QueryContractInfoResponse, QueryContractsByCodeRequest, QueryContractsByCodeResponse,
-    QueryRawContractStateRequest, QueryRawContractStateResponse, QuerySmartContractStateRequest,
-    QuerySmartContractStateResponse,
+    QueryAllContractStateRequest, QueryAllContractStateResponse, QueryCodeRequest,
+    QueryCodeResponse, QueryCodesRequest, QueryCodesResponse, QueryContractHistoryRequest,
+    QueryContractHistoryResponse, QueryContractInfoRequest, QueryContractInfoResponse,
+    QueryContractsByCodeRequest, QueryContractsByCodeResponse, QueryRawContractStateRequest,
+    QueryRawContractStateResponse, QuerySmartContractStateRequest, QuerySmartContractStateResponse,
 };
 use cosmrs::tendermint::{block, chain, Hash};
 use cosmrs::{AccountId, Coin as CosmosCoin, Tx};
-use log::trace;
 use prost::Message;
 use serde::{Deserialize, Serialize};

@@ -68,7 +67,7 @@ pub trait CosmWasmClient: TendermintRpcClient {
        Res: Message + Default,
    {
        if let Some(ref abci_path) = path {
-            trace!("performing query on abci path {abci_path}")
+            tracing::trace!("performing query on abci path {abci_path}")
        }
        let mut buf = Vec::with_capacity(req.encoded_len());
        req.encode(&mut buf)?;
@@ -154,13 +153,20 @@ pub trait CosmWasmClient: TendermintRpcClient {
            let req = QueryAllBalancesRequest {
                address: address.to_string(),
                pagination,
+                resolve_denom: false,
            };

            let mut res = self
                .make_abci_query::<_, QueryAllBalancesResponse>(path.clone(), req)
                .await?;

+            let early_break = res.balances.is_empty();
            raw_balances.append(&mut res.balances);
+
+            if early_break {
+                break;
+            }
+
            if let Some(next_key) = next_page_key(res.pagination) {
                pagination = Some(create_pagination(next_key))
            } else {
@@ -188,7 +194,13 @@ pub trait CosmWasmClient: TendermintRpcClient {
                .make_abci_query::<_, QueryTotalSupplyResponse>(path.clone(), req)
                .await?;

+            let early_break = res.supply.is_empty();
            supply.append(&mut res.supply);
+
+            if early_break {
+                break;
+            }
+
            if let Some(next_key) = next_page_key(res.pagination) {
                pagination = Some(create_pagination(next_key))
            } else {
@@ -218,17 +230,19 @@ pub trait CosmWasmClient: TendermintRpcClient {

        loop {
            let mut res = self
-                .tx_search(query.clone(), false, page, 100, Order::Ascending)
+                .tx_search(query.clone(), false, page, per_page, Order::Ascending)
                .await?;

-            results.append(&mut res.txs);
            // sanity check for if tendermint's maximum per_page was modified -
            // we don't want to accidentally be stuck in an infinite loop
-            if res.total_count == 0 || res.txs.is_empty() {
+            let early_break = res.total_count == 0 || res.txs.is_empty();
+            results.append(&mut res.txs);
+
+            if early_break {
                break;
            }

-            if res.total_count >= per_page {
+            if res.total_count > results.len() as u32 {
                page += 1
            } else {
                break;
@@ -295,7 +309,7 @@ pub trait CosmWasmClient: TendermintRpcClient {

        let start = Instant::now();
        loop {
-            log::debug!(
+            tracing::debug!(
                "Polling for result of including {} in a block...",
                broadcasted.hash
            );
@@ -327,7 +341,13 @@ pub trait CosmWasmClient: TendermintRpcClient {
                .make_abci_query::<_, QueryCodesResponse>(path.clone(), req)
                .await?;

+            let early_break = res.code_infos.is_empty();
            raw_codes.append(&mut res.code_infos);
+
+            if early_break {
+                break;
+            }
+
            if let Some(next_key) = next_page_key(res.pagination) {
                pagination = Some(create_pagination(next_key))
            } else {
@@ -372,7 +392,13 @@ pub trait CosmWasmClient: TendermintRpcClient {
                .make_abci_query::<_, QueryContractsByCodeResponse>(path.clone(), req)
                .await?;

+            let early_break = res.contracts.is_empty();
            raw_contracts.append(&mut res.contracts);
+
+            if early_break {
+                break;
+            }
+
            if let Some(next_key) = next_page_key(res.pagination) {
                pagination = Some(create_pagination(next_key))
            } else {
@@ -428,7 +454,13 @@ pub trait CosmWasmClient: TendermintRpcClient {
                .make_abci_query::<_, QueryContractHistoryResponse>(path.clone(), req)
                .await?;

+            let early_break = res.entries.is_empty();
            raw_entries.append(&mut res.entries);
+
+            if early_break {
+                break;
+            }
+
            if let Some(next_key) = next_page_key(res.pagination) {
                pagination = Some(create_pagination(next_key))
            } else {
@@ -442,6 +474,38 @@ pub trait CosmWasmClient: TendermintRpcClient {
            .collect::<Result<_, _>>()?)
    }

+    async fn query_all_contract_state(&self, address: &AccountId) -> Result<Vec<Model>, NyxdError> {
+        let path = Some("/cosmwasm.wasm.v1.Query/AllContractState".to_owned());
+
+        let mut models = Vec::new();
+        let mut pagination = None;
+
+        loop {
+            let req = QueryAllContractStateRequest {
+                address: address.to_string(),
+                pagination,
+            };
+
+            let mut res = self
+                .make_abci_query::<_, QueryAllContractStateResponse>(path.clone(), req)
+                .await?;
+
+            let empty_response = res.models.is_empty();
+            models.append(&mut res.models);
+
+            if empty_response {
+                break;
+            }
+            if let Some(next_key) = next_page_key(res.pagination) {
+                pagination = Some(create_pagination(next_key))
+            } else {
+                break;
+            }
+        }
+
+        Ok(models.into_iter().map(Into::into).collect())
+    }
+
    async fn query_contract_raw(
        &self,
        address: &AccountId,
@@ -488,7 +552,7 @@ pub trait CosmWasmClient: TendermintRpcClient {
            .make_abci_query::<_, QuerySmartContractStateResponse>(path, req)
            .await?;

-        trace!("raw query response: {}", String::from_utf8_lossy(&res.data));
+        tracing::trace!("raw query response: {}", String::from_utf8_lossy(&res.data));
        Ok(serde_json::from_slice(&res.data)?)
    }

@@ -27,13 +27,34 @@ use cosmrs::vesting::{
 };
 use cosmrs::{AccountId, Any, Coin as CosmosCoin};
 use prost::Message;
-use serde::Serialize;
+use serde::{Deserialize, Serialize};

 pub use cosmrs::abci::GasInfo;
 pub use cosmrs::abci::MsgResponse;

 pub type ContractCodeId = u64;

+// yet another thing to put in cosmrs
+#[derive(Serialize, Deserialize)]
+pub struct Model {
+    #[serde(with = "nym_serde_helpers::hex")]
+    pub key: Vec<u8>,
+
+    #[serde(with = "nym_serde_helpers::base64")]
+    pub value: Vec<u8>,
+}
+
+// follow the cosmwasm serialisation format, i.e. hex for key and base64 for value
+
+impl From<cosmrs::proto::cosmwasm::wasm::v1::Model> for Model {
+    fn from(model: cosmrs::proto::cosmwasm::wasm::v1::Model) -> Self {
+        Model {
+            key: model.key,
+            value: model.value,
+        }
+    }
+}
+
 #[derive(Serialize)]
 pub struct EmptyMsg {}

@@ -4,9 +4,11 @@
 use crate::rpc::TendermintRpcClient;
 use async_trait::async_trait;
 use base64::Engine;
+use cosmrs::tendermint;
 use cosmrs::tendermint::{block::Height, evidence::Evidence, Hash};
 use reqwest::header::HeaderMap;
 use reqwest::{header, RequestBuilder};
+use tendermint_rpc::dialect::{v0_34, v0_37, v0_38, LatestDialect};
 use tendermint_rpc::{
    client::CompatMode,
    dialect::{self, Dialect},
@@ -21,8 +23,21 @@ macro_rules! perform_with_compat {
    ($self:expr, $request:expr) => {{
        let request = $request;
        match $self.compat {
-            CompatMode::V0_37 => $self.perform_v0_37(request).await,
-            CompatMode::V0_34 => $self.perform_v0_34(request).await,
+            CompatMode::V0_38 => {
+                $self
+                    .perform_request_with_dialect(request, dialect::v0_38::Dialect)
+                    .await
+            }
+            CompatMode::V0_37 => {
+                $self
+                    .perform_request_with_dialect(request, dialect::v0_37::Dialect)
+                    .await
+            }
+            CompatMode::V0_34 => {
+                $self
+                    .perform_request_with_dialect(request, dialect::v0_34::Dialect)
+                    .await
+            }
        }
    }};
 }
@@ -70,7 +85,11 @@ impl ReqwestRpcClient {
            .headers(headers)
    }

-    async fn perform_request<R, S>(&self, request: R) -> Result<R::Output, Error>
+    async fn perform_request_with_dialect<R, S>(
+        &self,
+        request: R,
+        _dialect: S,
+    ) -> Result<R::Output, Error>
    where
        R: SimpleRequest<S>,
        S: Dialect,
@@ -81,26 +100,25 @@ impl ReqwestRpcClient {
            .send()
            .await
            .map_err(TendermintRpcErrorMap::into_rpc_err)?;
+        let response_status = response.status();
        let bytes = response
            .bytes()
            .await
            .map_err(TendermintRpcErrorMap::into_rpc_err)?;
+
+        // Successful JSON-RPC requests are expected to return a 200 OK HTTP status.
+        // Otherwise, this means that the HTTP request failed as a whole,
+        // as opposed to the JSON-RPC request returning an error,
+        // and we cannot expect the response body to be a valid JSON-RPC response.
+        if response_status != reqwest::StatusCode::OK {
+            // hehe, that's so nasty but we have to somehow convert between different versions of the same lib
+            return Err(Error::http_request_failed(
+                response_status.as_u16().try_into().unwrap(),
+            ));
+        }
+
        R::Response::from_string(bytes).map(Into::into)
    }
-
-    async fn perform_v0_34<R>(&self, request: R) -> Result<R::Output, Error>
-    where
-        R: SimpleRequest<dialect::v0_34::Dialect>,
-    {
-        self.perform_request(request).await
-    }
-
-    async fn perform_v0_37<R>(&self, request: R) -> Result<R::Output, Error>
-    where
-        R: SimpleRequest<dialect::v0_37::Dialect>,
-    {
-        self.perform_request(request).await
-    }
 }

 trait TendermintRpcErrorMap {
@@ -120,18 +138,50 @@ impl TendermintRpcClient for ReqwestRpcClient {
    where
        R: SimpleRequest,
    {
-        self.perform_request(request).await
+        self.perform_request_with_dialect(request, LatestDialect)
+            .await
    }

-    async fn block_results<H>(&self, height: H) -> Result<block_results::Response, Error>
+    async fn block<H>(&self, height: H) -> Result<endpoint::block::Response, Error>
    where
        H: Into<Height> + Send,
    {
-        perform_with_compat!(self, block_results::Request::new(height.into()))
+        perform_with_compat!(self, endpoint::block::Request::new(height.into()))
    }

-    async fn latest_block_results(&self) -> Result<block_results::Response, Error> {
-        perform_with_compat!(self, block_results::Request::default())
+    async fn block_by_hash(
+        &self,
+        hash: tendermint::Hash,
+    ) -> Result<endpoint::block_by_hash::Response, Error> {
+        perform_with_compat!(self, endpoint::block_by_hash::Request::new(hash))
+    }
+
+    async fn latest_block(&self) -> Result<endpoint::block::Response, Error> {
+        perform_with_compat!(self, endpoint::block::Request::default())
+    }
+
+    async fn block_results<H>(&self, height: H) -> Result<endpoint::block_results::Response, Error>
+    where
+        H: Into<Height> + Send,
+    {
+        perform_with_compat!(self, endpoint::block_results::Request::new(height.into()))
+    }
+
+    async fn latest_block_results(&self) -> Result<endpoint::block_results::Response, Error> {
+        perform_with_compat!(self, endpoint::block_results::Request::default())
+    }
+
+    async fn block_search(
+        &self,
+        query: Query,
+        page: u32,
+        per_page: u8,
+        order: Order,
+    ) -> Result<endpoint::block_search::Response, Error> {
+        perform_with_compat!(
+            self,
+            endpoint::block_search::Request::new(query, page, per_page, order)
+        )
    }

    async fn header<H>(&self, height: H) -> Result<endpoint::header::Response, Error>
@@ -140,11 +190,26 @@ impl TendermintRpcClient for ReqwestRpcClient {
    {
        let height = height.into();
        match self.compat {
-            CompatMode::V0_37 => self.perform(endpoint::header::Request::new(height)).await,
+            CompatMode::V0_38 => {
+                self.perform_request_with_dialect(
+                    endpoint::header::Request::new(height),
+                    v0_38::Dialect,
+                )
+                .await
+            }
+            CompatMode::V0_37 => {
+                self.perform_request_with_dialect(
+                    endpoint::header::Request::new(height),
+                    v0_37::Dialect,
+                )
+                .await
+            }
            CompatMode::V0_34 => {
                // Back-fill with a request to /block endpoint and
                // taking just the header from the response.
-                let resp = self.perform_v0_34(block::Request::new(height)).await?;
+                let resp = self
+                    .perform_request_with_dialect(block::Request::new(height), v0_34::Dialect)
+                    .await?;
                Ok(resp.into())
            }
        }
@@ -152,12 +217,25 @@ impl TendermintRpcClient for ReqwestRpcClient {

    async fn header_by_hash(&self, hash: Hash) -> Result<header_by_hash::Response, Error> {
        match self.compat {
-            CompatMode::V0_37 => self.perform(header_by_hash::Request::new(hash)).await,
+            CompatMode::V0_38 => {
+                self.perform_request_with_dialect(
+                    header_by_hash::Request::new(hash),
+                    v0_38::Dialect,
+                )
+                .await
+            }
+            CompatMode::V0_37 => {
+                self.perform_request_with_dialect(
+                    header_by_hash::Request::new(hash),
+                    v0_37::Dialect,
+                )
+                .await
+            }
            CompatMode::V0_34 => {
                // Back-fill with a request to /block_by_hash endpoint and
                // taking just the header from the response.
                let resp = self
-                    .perform_v0_34(block_by_hash::Request::new(hash))
+                    .perform_request_with_dialect(block_by_hash::Request::new(hash), v0_34::Dialect)
                    .await?;
                Ok(resp.into())
            }
@@ -167,8 +245,18 @@ impl TendermintRpcClient for ReqwestRpcClient {
    /// `/broadcast_evidence`: broadcast an evidence.
    async fn broadcast_evidence(&self, e: Evidence) -> Result<evidence::Response, Error> {
        match self.compat {
-            CompatMode::V0_37 => self.perform(evidence::Request::new(e)).await,
-            CompatMode::V0_34 => self.perform_v0_34(evidence::Request::new(e)).await,
+            CompatMode::V0_38 => {
+                self.perform_request_with_dialect(evidence::Request::new(e), v0_38::Dialect)
+                    .await
+            }
+            CompatMode::V0_37 => {
+                self.perform_request_with_dialect(evidence::Request::new(e), v0_37::Dialect)
+                    .await
+            }
+            CompatMode::V0_34 => {
+                self.perform_request_with_dialect(evidence::Request::new(e), v0_34::Dialect)
+                    .await
+            }
        }
    }

@@ -8,11 +8,11 @@ license.workspace = true
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

 [dependencies]
-dirs = { version = "5.0.1", optional = true }
+dirs = { workspace = true, optional = true }
 handlebars = { workspace = true }
 log = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
-toml = "0.7.4"
+toml = { workspace = true }
 url = { workspace = true }

 nym-network-defaults = { path = "../network-defaults", features = ["utoipa"] }
@@ -20,4 +20,4 @@ thiserror = { workspace = true }
 serde_json = { workspace = true }

 [build-dependencies]
-vergen = { version = "=8.3.1", features = ["build", "git", "gitcl", "rustc", "cargo"] }
+vergen = { workspace = true, features = ["build", "git", "gitcl", "rustc", "cargo"] }
@@ -4,11 +4,9 @@ version = "0.1.0"
 edition = "2021"
 license.workspace = true

-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
 [dependencies]
 cosmwasm-schema = { workspace = true }
-cw4 = { workspace = true }
 cw-controllers = { workspace = true }
+cw4 = { workspace = true }
 schemars = { workspace = true }
-serde = { version = "1.0.210", default-features = false, features = ["derive"] }
+serde = { workspace = true, features = ["derive"] }
@@ -9,7 +9,7 @@ license = { workspace = true }
 repository = { workspace = true }

 [dependencies]
-bs58 = "0.5.1"
+bs58 = { workspace = true }
 cosmwasm-std = { workspace = true }
 cosmwasm-schema = { workspace = true }
 cw-controllers = { workspace = true }
@@ -4,15 +4,13 @@ version = "0.1.0"
 edition = "2021"
 license.workspace = true

-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
 [dependencies]
+cosmwasm-schema = { workspace = true }
+cosmwasm-std = { workspace = true }
+cw-storage-plus = { workspace = true }
 cw-utils = { workspace = true }
 cw3 = { workspace = true }
 cw4 = { workspace = true }
-cw-storage-plus = { workspace = true }
-cosmwasm-schema = { workspace = true }
-cosmwasm-std = { workspace = true }
 schemars = { workspace = true }
-serde = { version = "1.0.210", default-features = false, features = ["derive"] }
+serde = { workspace = true, features = ["derive"] }
 thiserror = { workspace = true }
@@ -171,10 +171,20 @@ impl SqliteEcashTicketbookManager {
        data: &[u8],
    ) -> Result<(), sqlx::Error> {
        sqlx::query!(
-            "INSERT INTO master_verification_key(epoch_id, serialised_key, serialization_revision) VALUES (?, ?, ?)",
+            r#"
+                INSERT OR IGNORE INTO master_verification_key(epoch_id, serialised_key, serialization_revision) VALUES (?, ?, ?);
+                UPDATE master_verification_key
+                    SET
+                        serialised_key = ?,
+                        serialization_revision = ?
+                     WHERE epoch_id = ?
+            "#,
            epoch_id,
            data,
-            serialisation_revision
+            serialisation_revision,
+            data,
+            serialisation_revision,
+            epoch_id
        )
        .execute(&self.connection_pool)
        .await?;
@@ -204,10 +214,20 @@ impl SqliteEcashTicketbookManager {
        data: &[u8],
    ) -> Result<(), sqlx::Error> {
        sqlx::query!(
-            "INSERT INTO coin_indices_signatures(epoch_id, serialised_signatures, serialization_revision) VALUES (?, ?, ?)",
+            r#"
+                INSERT OR IGNORE INTO coin_indices_signatures(epoch_id, serialised_signatures, serialization_revision) VALUES (?, ?, ?);
+                UPDATE coin_indices_signatures
+                    SET
+                        serialised_signatures = ?,
+                        serialization_revision = ?
+                     WHERE epoch_id = ?
+            "#,
            epoch_id,
            data,
-            serialisation_revision
+            serialisation_revision,
+            data,
+            serialisation_revision,
+            epoch_id,
        )
        .execute(&self.connection_pool)
        .await?;
@@ -240,13 +260,21 @@ impl SqliteEcashTicketbookManager {
    ) -> Result<(), sqlx::Error> {
        sqlx::query!(
            r#"
-                INSERT INTO expiration_date_signatures(expiration_date, epoch_id, serialised_signatures, serialization_revision)
-                VALUES (?, ?, ?, ?)
+                INSERT OR IGNORE INTO expiration_date_signatures(expiration_date, epoch_id, serialised_signatures, serialization_revision)
+                VALUES (?, ?, ?, ?);
+                UPDATE expiration_date_signatures
+                    SET
+                        serialised_signatures = ?,
+                        serialization_revision = ?
+                     WHERE expiration_date = ?
            "#,
            expiration_date,
            epoch_id,
            data,
-            serialisation_revision
+            serialisation_revision,
+            data,
+            serialisation_revision,
+            expiration_date
        )
            .execute(&self.connection_pool)
            .await?;
@@ -1,6 +1,9 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+use crate::error::*;
+use crate::BandwidthFlushingBehaviourConfig;
+use crate::ClientBandwidth;
 use nym_credentials::ecash::utils::ecash_today;
 use nym_credentials_interface::Bandwidth;
 use nym_gateway_requests::ServerResponse;
@@ -9,10 +12,6 @@ use si_scale::helpers::bibytes2;
 use time::OffsetDateTime;
 use tracing::*;

-use crate::error::*;
-use crate::BandwidthFlushingBehaviourConfig;
-use crate::ClientBandwidth;
-
 const FREE_TESTNET_BANDWIDTH_VALUE: Bandwidth = Bandwidth::new_unchecked(64 * 1024 * 1024 * 1024); // 64GB

 #[derive(Clone)]
@@ -41,9 +40,13 @@ impl<S: Storage + Clone + 'static> BandwidthStorageManager<S> {
        }
    }

+    pub async fn available_bandwidth(&self) -> i64 {
+        self.client_bandwidth.available().await
+    }
+
    async fn sync_expiration(&mut self) -> Result<()> {
        self.storage
-            .set_expiration(self.client_id, self.client_bandwidth.bandwidth.expiration)
+            .set_expiration(self.client_id, self.client_bandwidth.expiration().await)
            .await?;
        Ok(())
    }
@@ -57,17 +60,17 @@ impl<S: Storage + Clone + 'static> BandwidthStorageManager<S> {

        self.increase_bandwidth(FREE_TESTNET_BANDWIDTH_VALUE, ecash_today())
            .await?;
-        let available_total = self.client_bandwidth.bandwidth.bytes;
+        let available_total = self.client_bandwidth.available().await;

        Ok(ServerResponse::Bandwidth { available_total })
    }

    #[instrument(skip_all)]
    pub async fn try_use_bandwidth(&mut self, required_bandwidth: i64) -> Result<i64> {
-        if self.client_bandwidth.bandwidth.expired() {
+        if self.client_bandwidth.expired().await {
            self.expire_bandwidth().await?;
        }
-        let available_bandwidth = self.client_bandwidth.bandwidth.bytes;
+        let available_bandwidth = self.client_bandwidth.available().await;

        if available_bandwidth < required_bandwidth {
            return Err(Error::OutOfBandwidth {
@@ -86,8 +89,7 @@ impl<S: Storage + Clone + 'static> BandwidthStorageManager<S> {

    async fn expire_bandwidth(&mut self) -> Result<()> {
        self.storage.reset_bandwidth(self.client_id).await?;
-        self.client_bandwidth.bandwidth = Default::default();
-        self.client_bandwidth.update_sync_data();
+        self.client_bandwidth.expire_bandwidth().await;
        Ok(())
    }

@@ -97,31 +99,31 @@ impl<S: Storage + Clone + 'static> BandwidthStorageManager<S> {
    ///
    /// * `amount`: amount to decrease the available bandwidth by.
    async fn consume_bandwidth(&mut self, amount: i64) -> Result<()> {
-        self.client_bandwidth.bandwidth.bytes -= amount;
-        self.client_bandwidth.bytes_delta_since_sync -= amount;
+        self.client_bandwidth.decrease_bandwidth(amount).await;

        // since we're going to be operating on a fair use policy anyway, even if we crash and let extra few packets
        // through, that's completely fine
-        if self.client_bandwidth.should_sync(self.bandwidth_cfg) {
-            self.sync_bandwidth().await?;
+        if self.client_bandwidth.should_sync(self.bandwidth_cfg).await {
+            self.sync_storage_bandwidth().await?;
        }

        Ok(())
    }

    #[instrument(level = "trace", skip_all)]
-    async fn sync_bandwidth(&mut self) -> Result<()> {
+    async fn sync_storage_bandwidth(&mut self) -> Result<()> {
        trace!("syncing client bandwidth with the underlying storage");
        let updated = self
            .storage
-            .increase_bandwidth(self.client_id, self.client_bandwidth.bytes_delta_since_sync)
+            .increase_bandwidth(
+                self.client_id,
+                self.client_bandwidth.delta_since_sync().await,
+            )
            .await?;

-        trace!(updated);
-
-        self.client_bandwidth.bandwidth.bytes = updated;
-
-        self.client_bandwidth.update_sync_data();
+        self.client_bandwidth
+            .resync_bandwidth_with_storage(updated)
+            .await;
        Ok(())
    }

@@ -136,13 +138,14 @@ impl<S: Storage + Clone + 'static> BandwidthStorageManager<S> {
        bandwidth: Bandwidth,
        expiration: OffsetDateTime,
    ) -> Result<()> {
-        self.client_bandwidth.bandwidth.bytes += bandwidth.value() as i64;
-        self.client_bandwidth.bytes_delta_since_sync += bandwidth.value() as i64;
-        self.client_bandwidth.bandwidth.expiration = expiration;
+        self.client_bandwidth
+            .increase_bandwidth(bandwidth.value() as i64, expiration)
+            .await;

        // any increases to bandwidth should get flushed immediately
        // (we don't want to accidentally miss somebody claiming a gigabyte voucher)
        self.sync_expiration().await?;
-        self.sync_bandwidth().await
+        self.sync_storage_bandwidth().await?;
+        Ok(())
    }
 }
@@ -1,10 +1,15 @@
 // Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use std::time::Duration;
-
+use nym_credentials::ecash::utils::ecash_today;
 use nym_credentials_interface::AvailableBandwidth;
+use std::sync::Arc;
+use std::time::Duration;
 use time::OffsetDateTime;
+use tokio::sync::RwLock;
+
+const DEFAULT_CLIENT_BANDWIDTH_MAX_FLUSHING_RATE: Duration = Duration::from_millis(5);
+const DEFAULT_CLIENT_BANDWIDTH_MAX_DELTA_FLUSHING_AMOUNT: i64 = 512 * 1024; // 512kB

 #[derive(Debug, Clone, Copy)]
 pub struct BandwidthFlushingBehaviourConfig {
@@ -15,10 +20,25 @@ pub struct BandwidthFlushingBehaviourConfig {
    pub client_bandwidth_max_delta_flushing_amount: i64,
 }

-#[derive(Debug, Clone, Copy)]
+impl Default for BandwidthFlushingBehaviourConfig {
+    fn default() -> Self {
+        Self {
+            client_bandwidth_max_flushing_rate: DEFAULT_CLIENT_BANDWIDTH_MAX_FLUSHING_RATE,
+            client_bandwidth_max_delta_flushing_amount:
+                DEFAULT_CLIENT_BANDWIDTH_MAX_DELTA_FLUSHING_AMOUNT,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
 pub struct ClientBandwidth {
+    inner: Arc<RwLock<ClientBandwidthInner>>,
+}
+
+#[derive(Debug)]
+struct ClientBandwidthInner {
    pub(crate) bandwidth: AvailableBandwidth,
-    pub(crate) last_flushed: OffsetDateTime,
+    pub(crate) last_synced: OffsetDateTime,

    /// the number of bytes the client had during the last sync.
    /// it is used to determine whether the current value should be synced with the storage
@@ -30,28 +50,74 @@ pub struct ClientBandwidth {
 impl ClientBandwidth {
    pub fn new(bandwidth: AvailableBandwidth) -> ClientBandwidth {
        ClientBandwidth {
-            bandwidth,
-            last_flushed: OffsetDateTime::now_utc(),
-            bytes_at_last_sync: bandwidth.bytes,
-            bytes_delta_since_sync: 0,
+            inner: Arc::new(RwLock::new(ClientBandwidthInner {
+                bandwidth,
+                last_synced: OffsetDateTime::now_utc(),
+                bytes_at_last_sync: bandwidth.bytes,
+                bytes_delta_since_sync: 0,
+            })),
        }
    }

-    pub(crate) fn should_sync(&self, cfg: BandwidthFlushingBehaviourConfig) -> bool {
-        if self.bytes_delta_since_sync.abs() >= cfg.client_bandwidth_max_delta_flushing_amount {
+    pub(crate) async fn should_sync(&self, cfg: BandwidthFlushingBehaviourConfig) -> bool {
+        let guard = self.inner.read().await;
+
+        if guard.bytes_delta_since_sync.abs() >= cfg.client_bandwidth_max_delta_flushing_amount {
            return true;
        }

-        if self.last_flushed + cfg.client_bandwidth_max_flushing_rate < OffsetDateTime::now_utc() {
+        if guard.last_synced + cfg.client_bandwidth_max_flushing_rate < OffsetDateTime::now_utc() {
            return true;
        }

        false
    }

-    pub(crate) fn update_sync_data(&mut self) {
-        self.last_flushed = OffsetDateTime::now_utc();
-        self.bytes_at_last_sync = self.bandwidth.bytes;
-        self.bytes_delta_since_sync = 0;
+    pub(crate) async fn available(&self) -> i64 {
+        self.inner.read().await.bandwidth.bytes
+    }
+
+    pub(crate) async fn delta_since_sync(&self) -> i64 {
+        self.inner.read().await.bytes_delta_since_sync
+    }
+    pub(crate) async fn expiration(&self) -> OffsetDateTime {
+        self.inner.read().await.bandwidth.expiration
+    }
+
+    pub(crate) async fn expired(&self) -> bool {
+        self.expiration().await < ecash_today()
+    }
+
+    pub(crate) async fn decrease_bandwidth(&self, decrease: i64) {
+        let mut guard = self.inner.write().await;
+
+        guard.bandwidth.bytes -= decrease;
+        guard.bytes_delta_since_sync -= decrease;
+    }
+
+    pub(crate) async fn increase_bandwidth(&self, increase: i64, new_expiration: OffsetDateTime) {
+        let mut guard = self.inner.write().await;
+
+        guard.bandwidth.bytes += increase;
+        guard.bandwidth.expiration = new_expiration;
+        guard.bytes_delta_since_sync += increase;
+    }
+
+    pub(crate) async fn expire_bandwidth(&self) {
+        let mut guard = self.inner.write().await;
+
+        guard.bandwidth = AvailableBandwidth::default();
+        guard.last_synced = OffsetDateTime::now_utc();
+        guard.bytes_at_last_sync = 0;
+        guard.bytes_delta_since_sync = 0;
+    }
+
+    pub(crate) async fn resync_bandwidth_with_storage(&self, stored: i64) {
+        let mut guard = self.inner.write().await;
+
+        guard.bandwidth.bytes = stored;
+        guard.bytes_at_last_sync = stored;
+        guard.bytes_delta_since_sync = 0;
+        guard.last_synced = OffsetDateTime::now_utc();
    }
 }
@@ -73,6 +73,10 @@ where
        self.shared_state.verification_key(epoch_id).await
    }

+    pub fn storage(&self) -> &S {
+        &self.shared_state.storage
+    }
+
    //Check for duplicate pay_info, then check the payment, then insert pay_info if everything succeeded
    pub async fn check_payment(
        &self,
@@ -150,7 +150,7 @@ impl<S: Storage + Clone + 'static> CredentialVerifier<S> {
        Ok(self
            .bandwidth_storage_manager
            .client_bandwidth
-            .bandwidth
-            .bytes)
+            .available()
+            .await)
    }
 }
@@ -8,7 +8,9 @@ license = { workspace = true }
 repository = { workspace = true }

 [dependencies]
+aes-gcm-siv = { workspace = true, optional = true }
 aes = { workspace = true, optional = true }
+aead = { workspace = true, optional = true }
 bs58 = { workspace = true }
 blake3 = { workspace = true, features = ["traits-preview"], optional = true }
 ctr = { workspace = true, optional = true }
@@ -21,7 +23,7 @@ x25519-dalek = { workspace = true, features = ["static_secrets"], optional = tru
 ed25519-dalek = { workspace = true, features = ["rand_core"], optional = true }
 rand = { workspace = true, optional = true }
 serde_bytes = { workspace = true, optional = true }
-serde = { version = "1.0", optional = true, default-features = false, features = ["derive"] }
+serde = { workspace = true, features = ["derive"], optional = true }
 subtle-encoding = { workspace = true, features = ["bech32-preview"] }
 thiserror = { workspace = true }
 zeroize = { workspace = true, optional = true, features = ["zeroize_derive"] }
@@ -35,9 +37,10 @@ rand_chacha = { workspace = true }

 [features]
 default = ["sphinx"]
+aead = ["dep:aead", "aead/std", "aes-gcm-siv", "generic-array"]
 serde = ["dep:serde", "serde_bytes", "ed25519-dalek/serde", "x25519-dalek/serde"]
 asymmetric = ["x25519-dalek", "ed25519-dalek", "zeroize"]
 hashing = ["blake3", "digest", "hkdf", "hmac", "generic-array"]
-symmetric = ["aes", "ctr", "cipher", "generic-array"]
+stream_cipher = ["aes", "ctr", "cipher", "generic-array"]
 sphinx = ["nym-sphinx-types/sphinx"]
 outfox = ["nym-sphinx-types/outfox"]
@@ -10,21 +10,22 @@ pub mod crypto_hash;
 pub mod hkdf;
 #[cfg(feature = "hashing")]
 pub mod hmac;
-#[cfg(all(feature = "asymmetric", feature = "hashing", feature = "symmetric"))]
+#[cfg(all(feature = "asymmetric", feature = "hashing", feature = "stream_cipher"))]
 pub mod shared_key;
-#[cfg(feature = "symmetric")]
 pub mod symmetric;

 #[cfg(feature = "hashing")]
 pub use digest::{Digest, OutputSizeUser};
-#[cfg(any(feature = "hashing", feature = "symmetric"))]
+#[cfg(any(feature = "hashing", feature = "stream_cipher", feature = "aead"))]
 pub use generic_array;

 // with the below my idea was to try to introduce having a single place of importing all hashing, encryption,
 // etc. algorithms and import them elsewhere as needed via common/crypto
-#[cfg(feature = "symmetric")]
+#[cfg(feature = "stream_cipher")]
 pub use aes;
+#[cfg(feature = "aead")]
+pub use aes_gcm_siv::{Aes128GcmSiv, Aes256GcmSiv};
 #[cfg(feature = "hashing")]
 pub use blake3;
-#[cfg(feature = "symmetric")]
+#[cfg(feature = "stream_cipher")]
 pub use ctr;
@@ -0,0 +1,98 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use aead::{Aead, AeadCore, AeadInPlace, Buffer, KeyInit, Payload};
+use generic_array::typenum::Unsigned;
+
+#[cfg(feature = "rand")]
+use rand::{CryptoRng, RngCore};
+
+pub use aead::{Error as AeadError, Key as AeadKey, KeySizeUser, Nonce, Tag};
+
+#[cfg(feature = "rand")]
+pub fn generate_key<A, R>(rng: &mut R) -> AeadKey<A>
+where
+    A: KeyInit,
+    R: RngCore + CryptoRng,
+{
+    let mut key = AeadKey::<A>::default();
+    rng.fill_bytes(&mut key);
+    key
+}
+
+#[cfg(feature = "rand")]
+pub fn random_nonce<A, R>(rng: &mut R) -> Nonce<A>
+where
+    A: AeadCore,
+    R: RngCore + CryptoRng,
+{
+    <A as AeadCore>::generate_nonce(rng)
+}
+
+pub fn nonce_size<A>() -> usize
+where
+    A: AeadCore,
+{
+    <<A as AeadCore>::NonceSize>::to_usize()
+}
+
+pub fn tag_size<A>() -> usize
+where
+    A: AeadCore,
+{
+    <<A as AeadCore>::TagSize>::to_usize()
+}
+
+#[inline]
+pub fn encrypt<'msg, 'aad, A>(
+    key: &AeadKey<A>,
+    nonce: &Nonce<A>,
+    plaintext: impl Into<Payload<'msg, 'aad>>,
+) -> Result<Vec<u8>, AeadError>
+where
+    A: Aead + KeyInit,
+{
+    let cipher = A::new(key);
+    cipher.encrypt(nonce, plaintext)
+}
+
+#[inline]
+pub fn decrypt<'msg, 'aad, A>(
+    key: &AeadKey<A>,
+    nonce: &Nonce<A>,
+    ciphertext: impl Into<Payload<'msg, 'aad>>,
+) -> Result<Vec<u8>, AeadError>
+where
+    A: Aead + KeyInit,
+{
+    let cipher = A::new(key);
+    cipher.decrypt(nonce, ciphertext)
+}
+
+#[inline]
+pub fn encrypt_in_place<A>(
+    key: &AeadKey<A>,
+    nonce: &Nonce<A>,
+    associated_data: &[u8],
+    buffer: &mut dyn Buffer,
+) -> Result<(), AeadError>
+where
+    A: AeadInPlace + KeyInit,
+{
+    let cipher = A::new(key);
+    cipher.encrypt_in_place(nonce, associated_data, buffer)
+}
+
+#[inline]
+pub fn decrypt_in_place<A>(
+    key: &AeadKey<A>,
+    nonce: &Nonce<A>,
+    associated_data: &[u8],
+    buffer: &mut dyn Buffer,
+) -> Result<(), AeadError>
+where
+    A: AeadInPlace + KeyInit,
+{
+    let cipher = A::new(key);
+    cipher.decrypt_in_place(nonce, associated_data, buffer)
+}
@@ -1,4 +1,7 @@
 // Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

+#[cfg(feature = "aead")]
+pub mod aead;
+#[cfg(feature = "stream_cipher")]
 pub mod stream_cipher;
@@ -2,12 +2,14 @@
 // SPDX-License-Identifier: Apache-2.0

 use cipher::{Iv, StreamCipher};
-pub use cipher::{IvSizeUser, KeyIvInit, KeySizeUser};
+use generic_array::typenum::Unsigned;
+
 #[cfg(feature = "rand")]
 use rand::{CryptoRng, RngCore};

 // re-export this for ease of use
 pub use cipher::Key as CipherKey;
+pub use cipher::{IvSizeUser, KeyIvInit, KeySizeUser};

 // SECURITY:
 // TODO: note that this is not the most secure approach here
@@ -36,7 +38,7 @@ where
 #[cfg(feature = "rand")]
 pub fn random_iv<C, R>(rng: &mut R) -> IV<C>
 where
-    C: KeyIvInit,
+    C: IvSizeUser,
    R: RngCore + CryptoRng,
 {
    let mut iv = IV::<C>::default();
@@ -44,16 +46,23 @@ where
    iv
 }

+pub fn iv_size<C>() -> usize
+where
+    C: IvSizeUser,
+{
+    <<C as IvSizeUser>::IvSize>::to_usize()
+}
+
 pub fn zero_iv<C>() -> IV<C>
 where
-    C: KeyIvInit,
+    C: IvSizeUser,
 {
    Iv::<C>::default()
 }

 pub fn iv_from_slice<C>(b: &[u8]) -> &IV<C>
 where
-    C: KeyIvInit,
+    C: IvSizeUser,
 {
    if b.len() != C::iv_size() {
        // `from_slice` would have caused a panic about this issue anyway.
@@ -166,6 +166,7 @@ impl Ciphertexts {
 #[derive(Zeroize)]
 #[zeroize(drop)]
 /// Randomness generated during ciphertext generation that is required for proofs of knowledge.
+///
 /// It must be handled with extreme care as its misuse might help malicious parties to recover
 /// the underlying plaintext.
 pub struct HazmatRandomness {
@@ -320,6 +320,8 @@ impl<'a> TryFrom<&'a nym_contracts_common::dealings::ContractSafeBytes> for Deal
    }
 }

+/// Try to recover the verification keys from the provided dealings.
+///
 /// Attempt to run the `VkCombine` algorithm to obtain the public master verification key, `VK`
 /// alongside shares of the verification key, `shvk_{1}`, `shvk_{2}`, ... `svhk_{n}`, where n is the number of receivers.
 ///
@@ -64,6 +64,8 @@ fn generate_lagrangian_coefficients_at_x(
    Ok(res)
 }

+/// Lagrange interpolation at x.
+///
 /// Performs a Lagrange interpolation at specified x for a polynomial defined by set of coordinates
 /// (x, f(x)), where x is a `Scalar` and f(x) is a generic type that can be obtained by evaluating `f` at `x`.
 /// It can be used for Scalars, G1 and G2 points.
@@ -85,6 +87,8 @@ where
        .sum())
 }

+/// Lagrange interpolation at the origin.
+///
 /// Performs a Lagrange interpolation at the origin for a polynomial defined by set of coordinates
 /// (x, f(x)), where x is a `Scalar` and f(x) is a generic type that can be obtained by evaluating `f` at `x`.
 /// It can be used for Scalars, G1 and G2 points.
@@ -17,11 +17,12 @@ generic-array = { workspace = true, features = ["serde"] }
 rand = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
+strum = { workspace = true }
 thiserror = { workspace = true }
 tracing = { workspace = true, features = ["log"] }
 zeroize = { workspace = true }

-nym-crypto = { path = "../crypto" }
+nym-crypto = { path = "../crypto", features = ["aead", "hashing"] }
 nym-pemstore = { path = "../pemstore" }
 nym-sphinx = { path = "../nymsphinx" }
 nym-task = { path = "../task" }
@@ -1,53 +1,47 @@
-// Copyright 2020 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2020-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use crate::iv::IV;
-use crate::registration::handshake::shared_key::SharedKeys;
-use nym_crypto::symmetric::stream_cipher;
-use nym_sphinx::params::GatewayEncryptionAlgorithm;
-use nym_sphinx::{DestinationAddressBytes, DESTINATION_ADDRESS_LENGTH};
+use crate::shared_key::{SharedGatewayKey, SharedKeyUsageError};
+use nym_sphinx::DestinationAddressBytes;
 use thiserror::Error;

-pub const ENCRYPTED_ADDRESS_SIZE: usize = DESTINATION_ADDRESS_LENGTH;
-
+/// Replacement for what used to be an `AuthToken`.
+///
 /// Replacement for what used to be an `AuthToken`. We used to be generating an `AuthToken` based on
 /// local secret and remote address in order to allow for authentication. Due to changes in registration
 /// and the fact we are deriving a shared key, we are encrypting remote's address with the previously
 /// derived shared key. If the value is as expected, then authentication is successful.
-#[derive(Debug, PartialEq, Eq, Hash, Clone, Copy)]
-pub struct EncryptedAddressBytes([u8; ENCRYPTED_ADDRESS_SIZE]);
+#[derive(Debug, PartialEq, Eq, Hash, Clone)]
+// this is no longer constant size due to the differences in ciphertext between aes128ctr and aes256gcm-siv (inclusion of tag)
+pub struct EncryptedAddressBytes(Vec<u8>);

 #[derive(Debug, Error)]
 pub enum EncryptedAddressConversionError {
    #[error("Failed to decode the encrypted address - {0}")]
    DecodeError(#[from] bs58::decode::Error),
-    #[error("The decoded address has invalid length")]
-    StringOfInvalidLengthError,
 }

 impl EncryptedAddressBytes {
-    pub fn new(address: &DestinationAddressBytes, key: &SharedKeys, iv: &IV) -> Self {
-        let ciphertext = stream_cipher::encrypt::<GatewayEncryptionAlgorithm>(
-            key.encryption_key(),
-            iv.inner(),
-            address.as_bytes_ref(),
-        );
+    pub fn new(
+        address: &DestinationAddressBytes,
+        key: &SharedGatewayKey,
+        nonce: &[u8],
+    ) -> Result<Self, SharedKeyUsageError> {
+        let ciphertext = key.encrypt_naive(address.as_bytes_ref(), Some(nonce))?;

-        let mut enc_address = [0u8; ENCRYPTED_ADDRESS_SIZE];
-        enc_address.copy_from_slice(&ciphertext[..]);
-        EncryptedAddressBytes(enc_address)
+        Ok(EncryptedAddressBytes(ciphertext))
    }

-    pub fn verify(&self, address: &DestinationAddressBytes, key: &SharedKeys, iv: &IV) -> bool {
-        self == &Self::new(address, key, iv)
-    }
-
-    pub fn from_bytes(bytes: [u8; ENCRYPTED_ADDRESS_SIZE]) -> Self {
-        EncryptedAddressBytes(bytes)
-    }
-
-    pub fn to_bytes(self) -> [u8; ENCRYPTED_ADDRESS_SIZE] {
-        self.0
+    pub fn verify(
+        &self,
+        address: &DestinationAddressBytes,
+        key: &SharedGatewayKey,
+        nonce: &[u8],
+    ) -> bool {
+        let Ok(reconstructed) = Self::new(address, key, nonce) else {
+            return false;
+        };
+        self == &reconstructed
    }

    pub fn as_bytes(&self) -> &[u8] {
@@ -58,14 +52,7 @@ impl EncryptedAddressBytes {
        val: S,
    ) -> Result<Self, EncryptedAddressConversionError> {
        let decoded = bs58::decode(val.into()).into_vec()?;
-
-        if decoded.len() != ENCRYPTED_ADDRESS_SIZE {
-            return Err(EncryptedAddressConversionError::StringOfInvalidLengthError);
-        }
-
-        let mut enc_address = [0u8; ENCRYPTED_ADDRESS_SIZE];
-        enc_address.copy_from_slice(&decoded[..]);
-        Ok(EncryptedAddressBytes(enc_address))
+        Ok(EncryptedAddressBytes(decoded))
    }

    pub fn to_base58_string(self) -> String {
@@ -1,76 +0,0 @@
-// Copyright 2020 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0
-
-use nym_crypto::generic_array::{typenum::Unsigned, GenericArray};
-use nym_crypto::symmetric::stream_cipher::{random_iv, IvSizeUser, IV as CryptoIV};
-use nym_sphinx::params::GatewayEncryptionAlgorithm;
-use rand::{CryptoRng, RngCore};
-use thiserror::Error;
-
-type NonceSize = <GatewayEncryptionAlgorithm as IvSizeUser>::IvSize;
-
-// I think 'IV' looks better than 'Iv', feel free to change that.
-#[allow(clippy::upper_case_acronyms)]
-pub struct IV(CryptoIV<GatewayEncryptionAlgorithm>);
-
-#[derive(Error, Debug)]
-// I think 'IV' looks better than 'Iv', feel free to change that.
-#[allow(clippy::upper_case_acronyms)]
-pub enum IVConversionError {
-    #[error("Failed to decode the iv - {0}")]
-    DecodeError(#[from] bs58::decode::Error),
-
-    #[error("The decoded bytes iv has invalid length")]
-    BytesOfInvalidLengthError,
-
-    #[error("The decoded string iv has invalid length")]
-    StringOfInvalidLengthError,
-}
-
-impl IV {
-    pub fn new_random<R: RngCore + CryptoRng>(rng: &mut R) -> Self {
-        IV(random_iv::<GatewayEncryptionAlgorithm, _>(rng))
-    }
-
-    pub fn try_from_bytes(bytes: &[u8]) -> Result<Self, IVConversionError> {
-        if bytes.len() != NonceSize::to_usize() {
-            return Err(IVConversionError::BytesOfInvalidLengthError);
-        }
-
-        Ok(IV(GenericArray::clone_from_slice(bytes)))
-    }
-
-    pub fn to_bytes(&self) -> Vec<u8> {
-        self.0.to_vec()
-    }
-
-    pub fn as_bytes(&self) -> &[u8] {
-        self.0.as_ref()
-    }
-
-    pub fn inner(&self) -> &CryptoIV<GatewayEncryptionAlgorithm> {
-        &self.0
-    }
-
-    pub fn try_from_base58_string<S: Into<String>>(val: S) -> Result<Self, IVConversionError> {
-        let decoded = bs58::decode(val.into()).into_vec()?;
-
-        if decoded.len() != NonceSize::to_usize() {
-            return Err(IVConversionError::StringOfInvalidLengthError);
-        }
-
-        Ok(IV(
-            GenericArray::from_exact_iter(decoded).expect("Invalid vector length!")
-        ))
-    }
-
-    pub fn to_base58_string(&self) -> String {
-        bs58::encode(self.to_bytes()).into_string()
-    }
-}
-
-impl From<IV> for String {
-    fn from(iv: IV) -> Self {
-        iv.to_base58_string()
-    }
-}
@@ -2,29 +2,35 @@
 // SPDX-License-Identifier: Apache-2.0

 pub use nym_crypto::generic_array;
-use nym_crypto::hmac::HmacOutput;
 use nym_crypto::OutputSizeUser;
 use nym_sphinx::params::GatewayIntegrityHmacAlgorithm;
+
 pub use types::*;

 pub mod authentication;
-pub mod iv;
 pub mod models;
 pub mod registration;
+pub mod shared_key;
 pub mod types;

-pub const CURRENT_PROTOCOL_VERSION: u8 = CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION;
+pub use shared_key::helpers::SymmetricKey;
+pub use shared_key::legacy::{LegacySharedKeySize, LegacySharedKeys};
+pub use shared_key::{
+    SharedGatewayKey, SharedKeyConversionError, SharedKeyUsageError, SharedSymmetricKey,
+};
+
+pub const CURRENT_PROTOCOL_VERSION: u8 = AES_GCM_SIV_PROTOCOL_VERSION;

 /// Defines the current version of the communication protocol between gateway and clients.
 /// It has to be incremented for any breaking change.
 // history:
 // 1 - initial release
 // 2 - changes to client credentials structure
+// 3 - change to AES-GCM-SIV and non-zero IVs
 pub const INITIAL_PROTOCOL_VERSION: u8 = 1;
 pub const CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION: u8 = 2;
-
-pub type GatewayMac = HmacOutput<GatewayIntegrityHmacAlgorithm>;
+pub const AES_GCM_SIV_PROTOCOL_VERSION: u8 = 3;

 // TODO: could using `Mac` trait here for OutputSize backfire?
 // Should hmac itself be exposed, imported and used instead?
-pub type GatewayMacSize = <GatewayIntegrityHmacAlgorithm as OutputSizeUser>::OutputSize;
+pub type LegacyGatewayMacSize = <GatewayIntegrityHmacAlgorithm as OutputSizeUser>::OutputSize;
@@ -1,129 +1,62 @@
 // Copyright 2020 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use crate::registration::handshake::shared_key::SharedKeys;
+use crate::registration::handshake::messages::{Finalization, GatewayMaterialExchange};
 use crate::registration::handshake::state::State;
+use crate::registration::handshake::SharedGatewayKey;
 use crate::registration::handshake::{error::HandshakeError, WsItem};
-use futures::future::BoxFuture;
-use futures::task::{Context, Poll};
-use futures::{Future, Sink, Stream};
-use nym_crypto::asymmetric::encryption::PUBLIC_KEY_SIZE;
-use nym_crypto::asymmetric::identity::SIGNATURE_LENGTH;
-use nym_crypto::asymmetric::{encryption, identity};
+use futures::{Sink, Stream};
 use rand::{CryptoRng, RngCore};
-use std::pin::Pin;
 use tungstenite::Message as WsMessage;

-pub(crate) struct ClientHandshake<'a> {
-    handshake_future: BoxFuture<'a, Result<SharedKeys, HandshakeError>>,
-}
-
-impl<'a> ClientHandshake<'a> {
-    pub(crate) fn new<S>(
-        rng: &mut (impl RngCore + CryptoRng),
-        ws_stream: &'a mut S,
-        identity: &'a nym_crypto::asymmetric::identity::KeyPair,
-        gateway_pubkey: identity::PublicKey,
-        expects_credential_usage: bool,
-        #[cfg(not(target_arch = "wasm32"))] shutdown: nym_task::TaskClient,
-    ) -> Self
+impl<'a, S, R> State<'a, S, R> {
+    async fn client_handshake_inner(&mut self) -> Result<(), HandshakeError>
    where
-        S: Stream<Item = WsItem> + Sink<WsMessage> + Unpin + Send + 'a,
+        S: Stream<Item = WsItem> + Sink<WsMessage> + Unpin,
+        R: CryptoRng + RngCore,
    {
-        let mut state = State::new(
-            rng,
-            ws_stream,
-            identity,
-            Some(gateway_pubkey),
-            expects_credential_usage,
-            #[cfg(not(target_arch = "wasm32"))]
-            shutdown,
-        );
+        // 1. if we're using non-legacy, i.e. aes256gcm-siv derivation, generate initiator salt for kdf
+        let maybe_hkdf_salt = self.maybe_generate_initiator_salt();

-        ClientHandshake {
-            handshake_future: Box::pin(async move {
-                // If any step along the way failed (that are non-network related),
-                // try to send 'error' message to the remote
-                // party to indicate handshake should be terminated
-                pub(crate) async fn check_processing_error<T, S>(
-                    result: Result<T, HandshakeError>,
-                    state: &mut State<'_, S>,
-                ) -> Result<T, HandshakeError>
-                where
-                    S: Sink<WsMessage> + Unpin,
-                {
-                    match result {
-                        Ok(ok) => Ok(ok),
-                        Err(err) => {
-                            state.send_handshake_error(err.to_string()).await?;
-                            Err(err)
-                        }
-                    }
-                }
+        // 1. send ed25519 pubkey alongside ephemeral x25519 pubkey and a hkdf salt if we're using non-legacy client
+        // LOCAL_ID_PUBKEY || EPHEMERAL_KEY || MAYBE_SALT
+        let init_message = self.init_message(maybe_hkdf_salt.clone());
+        self.send_handshake_data(init_message).await?;

-                let init_message = state.init_message();
-                state.send_handshake_data(init_message).await?;
+        // 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
+            .receive_handshake_message::<GatewayMaterialExchange>()
+            .await?;

-                // <- g^y || AES(k, sig(gate_priv, (g^y || g^x))
-                let mid_res = state.receive_handshake_message().await?;
-                let (remote_ephemeral_key, remote_key_material) =
-                    check_processing_error(Self::parse_mid_response(mid_res), &mut state).await?;
+        // 3. derive shared keys locally
+        // hkdf::<blake3>::(g^xy)
+        self.derive_shared_key(&mid_res.ephemeral_dh, maybe_hkdf_salt.as_deref());

-                // hkdf::<blake3>::(g^xy)
-                state.derive_shared_key(&remote_ephemeral_key);
-                let verification_res =
-                    state.verify_remote_key_material(&remote_key_material, &remote_ephemeral_key);
-                check_processing_error(verification_res, &mut state).await?;
+        // 4. verify the received signature using the locally derived keys
+        self.verify_remote_key_material(&mid_res.materials, &mid_res.ephemeral_dh)?;

-                // AES(k, sig(client_priv, (g^y || g^x))
-                let material = state.prepare_key_material_sig(&remote_ephemeral_key);
+        // 5. produce our own materials to get verified by the remote
+        // -> AES(k, sig(client_priv, g^x || g^y)) || MAYBE_NONCE
+        let materials = self.prepare_key_material_sig(&mid_res.ephemeral_dh)?;
+        self.send_handshake_data(materials).await?;

-                // -> AES(k, sig(client_priv, g^x || g^y))
-                state.send_handshake_data(material).await?;
-
-                // <- Ok
-                let finalization = state.receive_handshake_message().await?;
-                check_processing_error(Self::parse_finalization_response(finalization), &mut state)
-                    .await?;
-                Ok(state.finalize_handshake())
-            }),
-        }
+        // 6. wait for remote confirmation of finalizing the handshake
+        let finalization = self.receive_handshake_message::<Finalization>().await?;
+        finalization.ensure_success()?;
+        Ok(())
    }

-    // client should have received
-    // G^y || AES(k, SIG(PRIV_GATE, G^y || G^x))
-    fn parse_mid_response(
-        mut resp: Vec<u8>,
-    ) -> Result<(encryption::PublicKey, Vec<u8>), HandshakeError> {
-        if resp.len() != PUBLIC_KEY_SIZE + SIGNATURE_LENGTH {
-            return Err(HandshakeError::MalformedResponse);
-        }
-
-        let remote_key_material = resp.split_off(PUBLIC_KEY_SIZE);
-        // this can only fail if the provided bytes have len different from PUBLIC_KEY_SIZE
-        // which is impossible
-        let remote_ephemeral_key = encryption::PublicKey::from_bytes(&resp).unwrap();
-        Ok((remote_ephemeral_key, remote_key_material))
-    }
-
-    fn parse_finalization_response(resp: Vec<u8>) -> Result<(), HandshakeError> {
-        if resp.len() != 1 {
-            return Err(HandshakeError::MalformedResponse);
-        }
-        if resp[0] == 1 {
-            Ok(())
-        } else if resp[0] == 0 {
-            Err(HandshakeError::HandshakeFailure)
-        } else {
-            Err(HandshakeError::MalformedResponse)
-        }
-    }
-}
-
-impl<'a> Future for ClientHandshake<'a> {
-    type Output = Result<SharedKeys, HandshakeError>;
-
-    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
-        Pin::new(&mut self.handshake_future).poll(cx)
+    pub(crate) async fn perform_client_handshake(
+        mut self,
+    ) -> Result<SharedGatewayKey, HandshakeError>
+    where
+        S: Stream<Item = WsItem> + Sink<WsMessage> + Unpin,
+        R: CryptoRng + RngCore,
+    {
+        let handshake_res = self.client_handshake_inner().await;
+        self.check_for_handshake_processing_error(handshake_res)
+            .await?;
+        Ok(self.finalize_handshake())
    }
 }
@@ -1,16 +1,20 @@
 // Copyright 2020 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use nym_crypto::asymmetric::identity;
+use crate::shared_key::SharedKeyUsageError;
 use thiserror::Error;

-#[derive(Debug, Clone, Error)]
+#[derive(Debug, Error)]
 pub enum HandshakeError {
-    #[error(
-        "received key material of invalid length - {0}. Expected: {}",
-        identity::SIGNATURE_LENGTH
-    )]
-    KeyMaterialOfInvalidSize(usize),
+    #[error("received key material of invalid length: {received}. Expected: {expected}")]
+    KeyMaterialOfInvalidSize { received: usize, expected: usize },
+
+    #[error("no nonce has been provided for aes256-gcm-siv key derivation")]
+    MissingNonceForCurrentKey,
+
+    #[error(transparent)]
+    KeyUsageFailure(#[from] SharedKeyUsageError),
+
    #[error("received invalid signature")]
    InvalidSignature,
    #[error("encountered network error")]
@@ -1,114 +1,66 @@
 // Copyright 2020 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use crate::registration::handshake::shared_key::SharedKeys;
+use crate::registration::handshake::messages::{
+    HandshakeMessage, Initialisation, MaterialExchange,
+};
 use crate::registration::handshake::state::State;
+use crate::registration::handshake::SharedGatewayKey;
 use crate::registration::handshake::{error::HandshakeError, WsItem};
-use futures::future::BoxFuture;
-use futures::task::{Context, Poll};
-use futures::{Future, Sink, Stream};
-use nym_crypto::asymmetric::encryption;
-use nym_task::TaskClient;
-use rand::{CryptoRng, RngCore};
-use std::pin::Pin;
+use futures::{Sink, Stream};
 use tungstenite::Message as WsMessage;

-pub(crate) struct GatewayHandshake<'a> {
-    handshake_future: BoxFuture<'a, Result<SharedKeys, HandshakeError>>,
-}
-
-impl<'a> GatewayHandshake<'a> {
-    pub(crate) fn new<S>(
-        rng: &mut (impl RngCore + CryptoRng),
-        ws_stream: &'a mut S,
-        identity: &'a nym_crypto::asymmetric::identity::KeyPair,
-        received_init_payload: Vec<u8>,
-        shutdown: TaskClient,
-    ) -> Self
+impl<'a, S, R> State<'a, S, R> {
+    async fn gateway_handshake_inner(
+        &mut self,
+        raw_init_message: Vec<u8>,
+    ) -> Result<(), HandshakeError>
    where
-        S: Stream<Item = WsItem> + Sink<WsMessage> + Unpin + Send + 'a,
+        S: Stream<Item = WsItem> + Sink<WsMessage> + Unpin,
    {
-        let mut state = State::new(rng, ws_stream, identity, None, true, shutdown);
-        GatewayHandshake {
-            handshake_future: Box::pin(async move {
-                // If any step along the way failed (that are non-network related),
-                // try to send 'error' message to the remote
-                // party to indicate handshake should be terminated
-                pub(crate) async fn check_processing_error<T, S>(
-                    result: Result<T, HandshakeError>,
-                    state: &mut State<'_, S>,
-                ) -> Result<T, HandshakeError>
-                where
-                    S: Sink<WsMessage> + Unpin,
-                {
-                    match result {
-                        Ok(ok) => Ok(ok),
-                        Err(err) => {
-                            state.send_handshake_error(err.to_string()).await?;
-                            Err(err)
-                        }
-                    }
-                }
+        // 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());

-                // init: <- pub_key || g^x
-                let (remote_identity, remote_ephemeral_key) = check_processing_error(
-                    State::<S>::parse_init_message(received_init_payload),
-                    &mut state,
-                )
-                .await?;
-                state.update_remote_identity(remote_identity);
+        // 2. derive shared keys locally
+        // hkdf::<blake3>::(g^xy)
+        self.derive_shared_key(
+            &init_message.ephemeral_dh,
+            init_message.initiator_salt.as_deref(),
+        );

-                // hkdf::<blake3>::(g^xy)
-                state.derive_shared_key(&remote_ephemeral_key);
+        // 3. send ephemeral x25519 pubkey alongside the encrypted signature
+        // g^y || AES(k, sig(gate_priv, (g^y || g^x))
+        let material = self
+            .prepare_key_material_sig(&init_message.ephemeral_dh)?
+            .attach_ephemeral_dh(*self.local_ephemeral_key());
+        self.send_handshake_data(material).await?;

-                // AES(k, sig(gate_priv, (g^y || g^x))
-                let material = state.prepare_key_material_sig(&remote_ephemeral_key);
+        // 4. wait for the remote response with their own encrypted signature
+        let materials = self.receive_handshake_message::<MaterialExchange>().await?;

-                // g^y || AES(k, sig(gate_priv, (g^y || g^x))
-                let handshake_payload = Self::combine_material_with_ephemeral_key(
-                    state.local_ephemeral_key(),
-                    material,
-                );
+        // 5. verify the received signature using the locally derived keys
+        self.verify_remote_key_material(&materials, &init_message.ephemeral_dh)?;

-                // -> g^y || AES(k, sig(gate_priv, (g^y || g^x))
-                state.send_handshake_data(handshake_payload).await?;
+        // 6. finally send the finalization message to conclude the exchange
+        let finalizer = self.finalization_message();
+        self.send_handshake_data(finalizer).await?;

-                // <- AES(k, sig(client_priv, g^x || g^y))
-                let remote_key_material = state.receive_handshake_message().await?;
-                let verification_res =
-                    state.verify_remote_key_material(&remote_key_material, &remote_ephemeral_key);
-                check_processing_error(verification_res, &mut state).await?;
-                let finalizer = Self::prepare_finalization_response();
-
-                // -> Ok
-                state.send_handshake_data(finalizer).await?;
-                Ok(state.finalize_handshake())
-            }),
-        }
+        Ok(())
    }

-    // create g^y || AES(k, sig(gate_priv, (g^y || g^x))
-    fn combine_material_with_ephemeral_key(
-        ephemeral_key: &encryption::PublicKey,
-        material: Vec<u8>,
-    ) -> Vec<u8> {
-        ephemeral_key
-            .to_bytes()
-            .iter()
-            .cloned()
-            .chain(material)
-            .collect()
-    }
-
-    fn prepare_finalization_response() -> Vec<u8> {
-        vec![1]
-    }
-}
-
-impl<'a> Future for GatewayHandshake<'a> {
-    type Output = Result<SharedKeys, HandshakeError>;
-
-    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
-        Pin::new(&mut self.handshake_future).poll(cx)
+    pub(crate) async fn perform_gateway_handshake(
+        mut self,
+        raw_init_message: Vec<u8>,
+    ) -> Result<SharedGatewayKey, HandshakeError>
+    where
+        S: Stream<Item = WsItem> + Sink<WsMessage> + Unpin,
+    {
+        let handshake_res = self.gateway_handshake_inner(raw_init_message).await;
+        self.check_for_handshake_processing_error(handshake_res)
+            .await?;
+        Ok(self.finalize_handshake())
    }
 }
@@ -0,0 +1,228 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::registration::handshake::error::HandshakeError;
+use crate::registration::handshake::KDF_SALT_LENGTH;
+use nym_crypto::asymmetric::{ed25519, x25519};
+use nym_crypto::symmetric::aead::{nonce_size, tag_size};
+use nym_sphinx::params::GatewayEncryptionAlgorithm;
+
+// it is vital nobody changes the serialisation implementation unless you have an EXTREMELY good reason,
+// as otherwise you have very high chance of breaking backwards compatibility
+pub trait HandshakeMessage {
+    fn into_bytes(self) -> Vec<u8>;
+
+    fn try_from_bytes(bytes: &[u8]) -> Result<Self, HandshakeError>
+    where
+        Self: Sized;
+}
+
+#[derive(Debug)]
+pub struct Initialisation {
+    pub identity: ed25519::PublicKey,
+    pub ephemeral_dh: x25519::PublicKey,
+    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>,
+    pub nonce: Option<Vec<u8>>,
+}
+
+impl MaterialExchange {
+    #[cfg(not(target_arch = "wasm32"))]
+    pub fn attach_ephemeral_dh(self, ephemeral_dh: x25519::PublicKey) -> GatewayMaterialExchange {
+        GatewayMaterialExchange {
+            ephemeral_dh,
+            materials: self,
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct GatewayMaterialExchange {
+    pub ephemeral_dh: x25519::PublicKey,
+    pub materials: MaterialExchange,
+}
+
+#[derive(Debug)]
+pub struct Finalization {
+    pub success: bool,
+}
+
+impl Finalization {
+    pub fn ensure_success(&self) -> Result<(), HandshakeError> {
+        if !self.success {
+            return Err(HandshakeError::HandshakeFailure);
+        }
+        Ok(())
+    }
+}
+
+impl HandshakeMessage for Initialisation {
+    // LOCAL_ID_PUBKEY || EPHEMERAL_KEY || MAYBE_SALT
+    // Eventually the ID_PUBKEY prefix will get removed and recipient will know
+    // initializer's identity from another source.
+    fn into_bytes(self) -> Vec<u8> {
+        let bytes = self
+            .identity
+            .to_bytes()
+            .into_iter()
+            .chain(self.ephemeral_dh.to_bytes());
+
+        if let Some(salt) = self.initiator_salt {
+            bytes.chain(salt).collect()
+        } else {
+            bytes.collect()
+        }
+    }
+
+    // this will need to be adjusted when REMOTE_ID_PUBKEY is removed
+    fn try_from_bytes(bytes: &[u8]) -> Result<Self, HandshakeError>
+    where
+        Self: Sized,
+    {
+        let legacy_len = ed25519::PUBLIC_KEY_LENGTH + x25519::PUBLIC_KEY_SIZE;
+        let current_len = legacy_len + KDF_SALT_LENGTH;
+        if bytes.len() != legacy_len && bytes.len() != current_len {
+            return Err(HandshakeError::MalformedRequest);
+        }
+
+        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
+        // which is impossible
+        let ephemeral_dh =
+            x25519::PublicKey::from_bytes(&bytes[ed25519::PUBLIC_KEY_LENGTH..legacy_len]).unwrap();
+
+        let initiator_salt = if bytes.len() == legacy_len {
+            None
+        } else {
+            Some(bytes[legacy_len..].to_vec())
+        };
+
+        Ok(Initialisation {
+            identity,
+            ephemeral_dh,
+            initiator_salt,
+        })
+    }
+}
+
+impl HandshakeMessage for MaterialExchange {
+    // AES(k, SIG(PRIV_GATE, G^y || G^x))
+    fn into_bytes(self) -> Vec<u8> {
+        if let Some(nonce) = self.nonce {
+            self.signature_ciphertext
+                .iter()
+                .cloned()
+                .chain(nonce)
+                .collect()
+        } else {
+            self.signature_ciphertext.to_vec()
+        }
+    }
+
+    fn try_from_bytes(bytes: &[u8]) -> Result<Self, HandshakeError>
+    where
+        Self: Sized,
+    {
+        // we expect to receive either:
+        // LEGACY: ed25519 signature ciphertext (64 bytes)
+        // CURRENT: ed25519 signature ciphertext (+ tag) + AES256-GCM-SIV nonce (76 bytes)
+        let legacy_len = ed25519::SIGNATURE_LENGTH;
+        let current_len = legacy_len
+            + tag_size::<GatewayEncryptionAlgorithm>()
+            + nonce_size::<GatewayEncryptionAlgorithm>();
+
+        if bytes.len() != legacy_len && bytes.len() != current_len {
+            return Err(HandshakeError::MalformedResponse);
+        }
+
+        let (signature_ciphertext, nonce) = if bytes.len() == current_len {
+            let ciphertext_len =
+                ed25519::SIGNATURE_LENGTH + tag_size::<GatewayEncryptionAlgorithm>();
+            (
+                bytes[..ciphertext_len].to_vec(),
+                Some(bytes[ciphertext_len..].to_vec()),
+            )
+        } else {
+            (bytes.to_vec(), None)
+        };
+
+        Ok(MaterialExchange {
+            signature_ciphertext,
+            nonce,
+        })
+    }
+}
+
+impl HandshakeMessage for GatewayMaterialExchange {
+    // G^y || AES(k, SIG(PRIV_GATE, G^y || G^x))
+    fn into_bytes(self) -> Vec<u8> {
+        self.ephemeral_dh
+            .to_bytes()
+            .into_iter()
+            .chain(self.materials.into_bytes())
+            .collect()
+    }
+
+    fn try_from_bytes(bytes: &[u8]) -> Result<Self, HandshakeError>
+    where
+        Self: Sized,
+    {
+        // we expect to receive either:
+        // LEGACY: x25519 pubkey + ed25519 signature ciphertext (96 bytes)
+        // CURRENT: x25519 pubkey + ed25519 signature ciphertext (+ tag)+ AES256-GCM-SIV nonce (124 bytes)
+        let legacy_len = x25519::PUBLIC_KEY_SIZE + ed25519::SIGNATURE_LENGTH;
+        let current_len = legacy_len
+            + nonce_size::<GatewayEncryptionAlgorithm>()
+            + tag_size::<GatewayEncryptionAlgorithm>();
+
+        if bytes.len() != legacy_len && bytes.len() != current_len {
+            return Err(HandshakeError::MalformedResponse);
+        }
+
+        // this can only fail if the provided bytes have len different from PUBLIC_KEY_SIZE
+        // which is impossible
+        let ephemeral_dh =
+            x25519::PublicKey::from_bytes(&bytes[..x25519::PUBLIC_KEY_SIZE]).unwrap();
+        let materials = MaterialExchange::try_from_bytes(&bytes[x25519::PUBLIC_KEY_SIZE..])?;
+
+        Ok(GatewayMaterialExchange {
+            ephemeral_dh,
+            materials,
+        })
+    }
+}
+
+impl HandshakeMessage for Finalization {
+    fn into_bytes(self) -> Vec<u8> {
+        if self.success {
+            vec![1]
+        } else {
+            vec![0]
+        }
+    }
+
+    fn try_from_bytes(bytes: &[u8]) -> Result<Self, HandshakeError>
+    where
+        Self: Sized,
+    {
+        if bytes.len() != 1 {
+            return Err(HandshakeError::MalformedResponse);
+        }
+
+        let success = bytes[0] == 1;
+        Ok(Finalization { success })
+    }
+}
@@ -1,17 +1,20 @@
-// Copyright 2020 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2020-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0

-use self::client::ClientHandshake;
 use self::error::HandshakeError;
-#[cfg(not(target_arch = "wasm32"))]
-use self::gateway::GatewayHandshake;
-pub use self::shared_key::{SharedKeySize, SharedKeys};
+use crate::registration::handshake::state::State;
+use crate::SharedGatewayKey;
+use futures::future::BoxFuture;
 use futures::{Sink, Stream};
 use nym_crypto::asymmetric::identity;
+use rand::{CryptoRng, RngCore};
+use std::future::Future;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tungstenite::{Error as WsError, Message as WsMessage};
+
 #[cfg(not(target_arch = "wasm32"))]
 use nym_task::TaskClient;
-use rand::{CryptoRng, RngCore};
-use tungstenite::{Error as WsError, Message as WsMessage};

 pub(crate) type WsItem = Result<WsMessage, WsError>;

@@ -19,49 +22,74 @@ mod client;
 pub mod error;
 #[cfg(not(target_arch = "wasm32"))]
 mod gateway;
-pub mod shared_key;
+mod messages;
 mod state;

+// realistically even 32bit would have sufficed, so 128 is definitely enough
+pub const KDF_SALT_LENGTH: usize = 16;
+
 // Note: the handshake is built on top of WebSocket, but in principle it shouldn't be too difficult
 // to remove that restriction, by just changing Sink<WsMessage> and Stream<Item = WsMessage> into
 // AsyncWrite and AsyncRead and slightly adjusting the implementation. But right now
 // we do not need to worry about that.

-pub async fn client_handshake<'a, S>(
-    rng: &mut (impl RngCore + CryptoRng),
+pub struct GatewayHandshake<'a> {
+    handshake_future: BoxFuture<'a, Result<SharedGatewayKey, HandshakeError>>,
+}
+
+impl<'a> Future for GatewayHandshake<'a> {
+    type Output = Result<SharedGatewayKey, HandshakeError>;
+
+    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        Pin::new(&mut self.handshake_future).poll(cx)
+    }
+}
+
+pub fn client_handshake<'a, S, R>(
+    rng: &'a mut R,
    ws_stream: &'a mut S,
    identity: &'a identity::KeyPair,
    gateway_pubkey: identity::PublicKey,
    expects_credential_usage: bool,
+    derive_aes256_gcm_siv_key: bool,
    #[cfg(not(target_arch = "wasm32"))] shutdown: TaskClient,
-) -> Result<SharedKeys, HandshakeError>
+) -> GatewayHandshake<'a>
 where
    S: Stream<Item = WsItem> + Sink<WsMessage> + Unpin + Send + 'a,
+    R: CryptoRng + RngCore + Send,
 {
-    ClientHandshake::new(
+    let state = State::new(
        rng,
        ws_stream,
        identity,
-        gateway_pubkey,
-        expects_credential_usage,
+        Some(gateway_pubkey),
        #[cfg(not(target_arch = "wasm32"))]
        shutdown,
    )
-    .await
+    .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()),
+    }
 }

 #[cfg(not(target_arch = "wasm32"))]
-pub async fn gateway_handshake<'a, S>(
-    rng: &mut (impl RngCore + CryptoRng),
+pub fn gateway_handshake<'a, S, R>(
+    rng: &'a mut R,
    ws_stream: &'a mut S,
    identity: &'a identity::KeyPair,
    received_init_payload: Vec<u8>,
    shutdown: TaskClient,
-) -> Result<SharedKeys, HandshakeError>
+) -> GatewayHandshake<'a>
 where
    S: Stream<Item = WsItem> + Sink<WsMessage> + Unpin + Send + 'a,
+    R: CryptoRng + RngCore + Send,
 {
-    GatewayHandshake::new(rng, ws_stream, identity, received_init_payload, shutdown).await
+    let state = State::new(rng, ws_stream, identity, None, shutdown);
+    GatewayHandshake {
+        handshake_future: Box::pin(state.perform_gateway_handshake(received_init_payload)),
+    }
 }

 /*
@@ -1,178 +0,0 @@
-// Copyright 2020-2023 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0
-
-use crate::{GatewayMacSize, GatewayRequestsError};
-use nym_crypto::generic_array::{
-    typenum::{Sum, Unsigned, U16},
-    GenericArray,
-};
-use nym_crypto::hmac::{compute_keyed_hmac, recompute_keyed_hmac_and_verify_tag};
-use nym_crypto::symmetric::stream_cipher::{self, CipherKey, KeySizeUser, IV};
-use nym_pemstore::traits::PemStorableKey;
-use nym_sphinx::params::{GatewayEncryptionAlgorithm, GatewayIntegrityHmacAlgorithm};
-use serde::{Deserialize, Serialize};
-use thiserror::Error;
-use zeroize::{Zeroize, ZeroizeOnDrop};
-
-// shared key is as long as the encryption key and the MAC key combined.
-pub type SharedKeySize = Sum<EncryptionKeySize, MacKeySize>;
-
-// we're using 16 byte long key in sphinx, so let's use the same one here
-type MacKeySize = U16;
-type EncryptionKeySize = <GatewayEncryptionAlgorithm as KeySizeUser>::KeySize;
-
-/// Shared key used when computing MAC for messages exchanged between client and its gateway.
-pub type MacKey = GenericArray<u8, MacKeySize>;
-
-#[derive(Debug, PartialEq, Serialize, Deserialize, Zeroize, ZeroizeOnDrop)]
-pub struct SharedKeys {
-    encryption_key: CipherKey<GatewayEncryptionAlgorithm>,
-    mac_key: MacKey,
-}
-
-#[derive(Debug, Clone, Copy, Error)]
-pub enum SharedKeyConversionError {
-    #[error("the string representation of the shared keys was malformed - {0}")]
-    DecodeError(#[from] bs58::decode::Error),
-    #[error(
-        "the received shared keys had invalid size. Got: {received}, but expected: {expected}"
-    )]
-    InvalidSharedKeysSize { received: usize, expected: usize },
-}
-
-impl SharedKeys {
-    pub fn try_from_bytes(bytes: &[u8]) -> Result<Self, SharedKeyConversionError> {
-        if bytes.len() != SharedKeySize::to_usize() {
-            return Err(SharedKeyConversionError::InvalidSharedKeysSize {
-                received: bytes.len(),
-                expected: SharedKeySize::to_usize(),
-            });
-        }
-
-        let encryption_key =
-            GenericArray::clone_from_slice(&bytes[..EncryptionKeySize::to_usize()]);
-        let mac_key = GenericArray::clone_from_slice(&bytes[EncryptionKeySize::to_usize()..]);
-
-        Ok(SharedKeys {
-            encryption_key,
-            mac_key,
-        })
-    }
-
-    /// Encrypts the provided data using the optionally provided initialisation vector,
-    /// or a 0 value if nothing was given. Then it computes an integrity mac and concatenates it
-    /// with the previously produced ciphertext.
-    pub fn encrypt_and_tag(
-        &self,
-        data: &[u8],
-        iv: Option<&IV<GatewayEncryptionAlgorithm>>,
-    ) -> Vec<u8> {
-        let encrypted_data = match iv {
-            Some(iv) => stream_cipher::encrypt::<GatewayEncryptionAlgorithm>(
-                self.encryption_key(),
-                iv,
-                data,
-            ),
-            None => {
-                let zero_iv = stream_cipher::zero_iv::<GatewayEncryptionAlgorithm>();
-                stream_cipher::encrypt::<GatewayEncryptionAlgorithm>(
-                    self.encryption_key(),
-                    &zero_iv,
-                    data,
-                )
-            }
-        };
-        let mac = compute_keyed_hmac::<GatewayIntegrityHmacAlgorithm>(
-            self.mac_key().as_slice(),
-            &encrypted_data,
-        );
-
-        mac.into_bytes().into_iter().chain(encrypted_data).collect()
-    }
-
-    pub fn decrypt_tagged(
-        &self,
-        enc_data: &[u8],
-        iv: Option<&IV<GatewayEncryptionAlgorithm>>,
-    ) -> Result<Vec<u8>, GatewayRequestsError> {
-        let mac_size = GatewayMacSize::to_usize();
-        if enc_data.len() < mac_size {
-            return Err(GatewayRequestsError::TooShortRequest);
-        }
-
-        let mac_tag = &enc_data[..mac_size];
-        let message_bytes = &enc_data[mac_size..];
-
-        if !recompute_keyed_hmac_and_verify_tag::<GatewayIntegrityHmacAlgorithm>(
-            self.mac_key().as_slice(),
-            message_bytes,
-            mac_tag,
-        ) {
-            return Err(GatewayRequestsError::InvalidMac);
-        }
-
-        // couldn't have made the first borrow mutable as you can't have an immutable borrow
-        // together with a mutable one
-        let message_bytes_mut = &mut enc_data.to_vec()[mac_size..];
-
-        let zero_iv = stream_cipher::zero_iv::<GatewayEncryptionAlgorithm>();
-        let iv = iv.unwrap_or(&zero_iv);
-        stream_cipher::decrypt_in_place::<GatewayEncryptionAlgorithm>(
-            self.encryption_key(),
-            iv,
-            message_bytes_mut,
-        );
-        Ok(message_bytes_mut.to_vec())
-    }
-
-    pub fn encryption_key(&self) -> &CipherKey<GatewayEncryptionAlgorithm> {
-        &self.encryption_key
-    }
-
-    pub fn mac_key(&self) -> &MacKey {
-        &self.mac_key
-    }
-
-    pub fn to_bytes(&self) -> Vec<u8> {
-        self.encryption_key
-            .iter()
-            .copied()
-            .chain(self.mac_key.iter().copied())
-            .collect()
-    }
-
-    pub fn try_from_base58_string<S: Into<String>>(
-        val: S,
-    ) -> Result<Self, SharedKeyConversionError> {
-        let decoded = bs58::decode(val.into()).into_vec()?;
-        SharedKeys::try_from_bytes(&decoded)
-    }
-
-    pub fn to_base58_string(&self) -> String {
-        bs58::encode(self.to_bytes()).into_string()
-    }
-}
-
-impl From<SharedKeys> for String {
-    fn from(keys: SharedKeys) -> Self {
-        keys.to_base58_string()
-    }
-}
-
-impl PemStorableKey for SharedKeys {
-    type Error = SharedKeyConversionError;
-
-    fn pem_type() -> &'static str {
-        // TODO: If common\nymsphinx\params\src\lib::GatewayIntegrityHmacAlgorithm changes
-        // the pem type needs updating!
-        "AES-128-CTR + HMAC-BLAKE3 GATEWAY SHARED KEYS"
-    }
-
-    fn to_bytes(&self) -> Vec<u8> {
-        self.to_bytes()
-    }
-
-    fn from_bytes(bytes: &[u8]) -> Result<Self, Self::Error> {
-        Self::try_from_bytes(bytes)
-    }
-}
@@ -2,26 +2,34 @@
 // SPDX-License-Identifier: Apache-2.0

 use crate::registration::handshake::error::HandshakeError;
-use crate::registration::handshake::shared_key::{SharedKeySize, SharedKeys};
-use crate::registration::handshake::WsItem;
-use crate::types;
+use crate::registration::handshake::messages::{
+    HandshakeMessage, Initialisation, MaterialExchange,
+};
+use crate::registration::handshake::{SharedGatewayKey, WsItem, KDF_SALT_LENGTH};
+use crate::shared_key::SharedKeySize;
+use crate::{
+    types, LegacySharedKeySize, LegacySharedKeys, SharedSymmetricKey, AES_GCM_SIV_PROTOCOL_VERSION,
+    CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION, INITIAL_PROTOCOL_VERSION,
+};
 use futures::{Sink, SinkExt, Stream, StreamExt};
+use nym_crypto::asymmetric::{ed25519, x25519};
+use nym_crypto::symmetric::aead::random_nonce;
 use nym_crypto::{
    asymmetric::{encryption, identity},
    generic_array::typenum::Unsigned,
    hkdf,
-    symmetric::stream_cipher,
 };
 use nym_sphinx::params::{GatewayEncryptionAlgorithm, GatewaySharedKeyHkdfAlgorithm};
-#[cfg(not(target_arch = "wasm32"))]
-use nym_task::TaskClient;
-use rand::{CryptoRng, RngCore};
-use tracing::log::*;
-
+use rand::{thread_rng, CryptoRng, RngCore};
+use std::any::{type_name, Any};
 use std::str::FromStr;
 use std::time::Duration;
+use tracing::log::*;
 use tungstenite::Message as WsMessage;

+#[cfg(not(target_arch = "wasm32"))]
+use nym_task::TaskClient;
+
 #[cfg(not(target_arch = "wasm32"))]
 use tokio::time::timeout;

@@ -29,113 +37,152 @@ use tokio::time::timeout;
 use wasmtimer::tokio::timeout;

 /// Handshake state.
-pub(crate) struct State<'a, S> {
+pub(crate) struct State<'a, S, R> {
    /// The underlying WebSocket stream.
    ws_stream: &'a mut S,

+    /// Pseudorandom number generator used during the exchange
+    rng: &'a mut R,
+
    /// Identity of the local "node" (client or gateway) which is used
    /// during the handshake.
-    identity: &'a identity::KeyPair,
+    identity: &'a ed25519::KeyPair,

    /// Local ephemeral Diffie-Hellman keypair generated as a part of the handshake.
-    ephemeral_keypair: encryption::KeyPair,
+    ephemeral_keypair: x25519::KeyPair,

    /// The derived shared key using the ephemeral keys of both parties.
-    derived_shared_keys: Option<SharedKeys>,
+    derived_shared_keys: Option<SharedGatewayKey>,

    /// The known or received public identity key of the remote.
    /// Ideally it would always be known before the handshake was initiated.
-    remote_pubkey: Option<identity::PublicKey>,
+    remote_pubkey: Option<ed25519::PublicKey>,

    // this field is really out of place here, however, we need to propagate this information somehow
    // in order to establish correct protocol for backwards compatibility reasons
    expects_credential_usage: bool,

+    /// Specifies whether the end product should be an AES128Ctr + blake3 HMAC keys (legacy) or AES256-GCM-SIV (current)
+    derive_aes256_gcm_siv_key: bool,
+
    // channel to receive shutdown signal
    #[cfg(not(target_arch = "wasm32"))]
    shutdown: TaskClient,
 }

-impl<'a, S> State<'a, S> {
+impl<'a, S, R> State<'a, S, R> {
    pub(crate) fn new(
-        rng: &mut (impl RngCore + CryptoRng),
+        rng: &'a mut R,
        ws_stream: &'a mut S,
        identity: &'a identity::KeyPair,
        remote_pubkey: Option<identity::PublicKey>,
-        expects_credential_usage: bool,
        #[cfg(not(target_arch = "wasm32"))] shutdown: TaskClient,
-    ) -> Self {
+    ) -> Self
+    where
+        R: CryptoRng + RngCore,
+    {
        let ephemeral_keypair = encryption::KeyPair::new(rng);
        State {
            ws_stream,
+            rng,
            ephemeral_keypair,
            identity,
            remote_pubkey,
            derived_shared_keys: None,
-            expects_credential_usage,
+            // later on this should become the default
+            expects_credential_usage: false,
+            derive_aes256_gcm_siv_key: false,
            #[cfg(not(target_arch = "wasm32"))]
            shutdown,
        }
    }

+    pub(crate) fn with_credential_usage(mut self, expects_credential_usage: bool) -> Self {
+        self.expects_credential_usage = expects_credential_usage;
+        self
+    }
+
+    pub(crate) fn with_aes256_gcm_siv_key(mut self, derive_aes256_gcm_siv_key: bool) -> Self {
+        self.derive_aes256_gcm_siv_key = derive_aes256_gcm_siv_key;
+        self
+    }
+
+    #[cfg(not(target_arch = "wasm32"))]
+    pub(crate) fn set_aes256_gcm_siv_key_derivation(&mut self, derive_aes256_gcm_siv_key: bool) {
+        self.derive_aes256_gcm_siv_key = derive_aes256_gcm_siv_key;
+    }
+
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn local_ephemeral_key(&self) -> &encryption::PublicKey {
        self.ephemeral_keypair.public_key()
    }

-    // LOCAL_ID_PUBKEY || EPHEMERAL_KEY
+    pub(crate) fn maybe_generate_initiator_salt(&mut self) -> Option<Vec<u8>>
+    where
+        R: CryptoRng + RngCore,
+    {
+        if self.derive_aes256_gcm_siv_key {
+            let mut salt = vec![0u8; KDF_SALT_LENGTH];
+            self.rng.fill_bytes(&mut salt);
+            Some(salt)
+        } else {
+            None
+        }
+    }
+
+    // LOCAL_ID_PUBKEY || EPHEMERAL_KEY || MAYBE_SALT
    // Eventually the ID_PUBKEY prefix will get removed and recipient will know
    // initializer's identity from another source.
-    pub(crate) fn init_message(&self) -> Vec<u8> {
-        self.identity
-            .public_key()
-            .to_bytes()
-            .into_iter()
-            .chain(self.ephemeral_keypair.public_key().to_bytes())
-            .collect()
-    }
-
-    // this will need to be adjusted when REMOTE_ID_PUBKEY is removed
-    #[cfg(not(target_arch = "wasm32"))]
-    pub(crate) fn parse_init_message(
-        mut init_message: Vec<u8>,
-    ) -> Result<(identity::PublicKey, encryption::PublicKey), HandshakeError> {
-        if init_message.len() != identity::PUBLIC_KEY_LENGTH + encryption::PUBLIC_KEY_SIZE {
-            return Err(HandshakeError::MalformedRequest);
+    pub(crate) fn init_message(&self, initiator_salt: Option<Vec<u8>>) -> Initialisation {
+        Initialisation {
+            identity: *self.identity.public_key(),
+            ephemeral_dh: *self.ephemeral_keypair.public_key(),
+            initiator_salt,
        }
-
-        let remote_ephemeral_key_bytes = init_message.split_off(identity::PUBLIC_KEY_LENGTH);
-        // this can only fail if the provided bytes have len different from encryption::PUBLIC_KEY_SIZE
-        // which is impossible
-        let remote_ephemeral_key =
-            encryption::PublicKey::from_bytes(&remote_ephemeral_key_bytes).unwrap();
-
-        // this could actually fail if the curve point fails to get decompressed
-        let remote_identity = identity::PublicKey::from_bytes(&init_message)
-            .map_err(|_| HandshakeError::MalformedRequest)?;
-
-        Ok((remote_identity, remote_ephemeral_key))
    }

-    pub(crate) fn derive_shared_key(&mut self, remote_ephemeral_key: &encryption::PublicKey) {
+    #[cfg(not(target_arch = "wasm32"))]
+    pub(crate) fn finalization_message(
+        &self,
+    ) -> crate::registration::handshake::messages::Finalization {
+        crate::registration::handshake::messages::Finalization { success: true }
+    }
+
+    pub(crate) fn derive_shared_key(
+        &mut self,
+        remote_ephemeral_key: &encryption::PublicKey,
+        initiator_salt: Option<&[u8]>,
+    ) {
        let dh_result = self
            .ephemeral_keypair
            .private_key()
            .diffie_hellman(remote_ephemeral_key);

+        let key_size = if self.derive_aes256_gcm_siv_key {
+            SharedKeySize::to_usize()
+        } else {
+            LegacySharedKeySize::to_usize()
+        };
+
        // there is no reason for this to fail as our okm is expected to be only 16 bytes
        let okm = hkdf::extract_then_expand::<GatewaySharedKeyHkdfAlgorithm>(
-            None,
+            initiator_salt,
            &dh_result,
            None,
-            SharedKeySize::to_usize(),
+            key_size,
        )
        .expect("somehow too long okm was provided");

-        let derived_shared_key =
-            SharedKeys::try_from_bytes(&okm).expect("okm was expanded to incorrect length!");
-
-        self.derived_shared_keys = Some(derived_shared_key)
+        let shared_key = if self.derive_aes256_gcm_siv_key {
+            let current_key = SharedSymmetricKey::try_from_bytes(&okm)
+                .expect("okm was expanded to incorrect length!");
+            SharedGatewayKey::Current(current_key)
+        } else {
+            let legacy_key = LegacySharedKeys::try_from_bytes(&okm)
+                .expect("okm was expanded to incorrect length!");
+            SharedGatewayKey::Legacy(legacy_key)
+        };
+        self.derived_shared_keys = Some(shared_key)
    }

    // produces AES(k, SIG(ID_PRIV, G^x || G^y),
@@ -143,47 +190,57 @@ impl<'a, S> State<'a, S> {
    pub(crate) fn prepare_key_material_sig(
        &self,
        remote_ephemeral_key: &encryption::PublicKey,
-    ) -> Vec<u8> {
-        let message: Vec<_> = self
+    ) -> Result<MaterialExchange, HandshakeError> {
+        let plaintext: Vec<_> = self
            .ephemeral_keypair
            .public_key()
            .to_bytes()
            .into_iter()
            .chain(remote_ephemeral_key.to_bytes())
            .collect();
+        let signature = self.identity.private_key().sign(plaintext);

-        let signature = self.identity.private_key().sign(message);
-        let zero_iv = stream_cipher::zero_iv::<GatewayEncryptionAlgorithm>();
-        stream_cipher::encrypt::<GatewayEncryptionAlgorithm>(
-            self.derived_shared_keys.as_ref().unwrap().encryption_key(),
-            &zero_iv,
-            &signature.to_bytes(),
-        )
+        let nonce = if self.derive_aes256_gcm_siv_key {
+            let mut rng = thread_rng();
+            Some(random_nonce::<GatewayEncryptionAlgorithm, _>(&mut rng).to_vec())
+        } else {
+            None
+        };
+
+        // SAFETY: this function is only called after the local key has already been derived
+        let signature_ciphertext = self
+            .derived_shared_keys
+            .as_ref()
+            .expect("shared key was not derived!")
+            .encrypt_naive(&signature.to_bytes(), nonce.as_deref())?;
+
+        Ok(MaterialExchange {
+            signature_ciphertext,
+            nonce,
+        })
    }

-    // must be called after shared key was derived locally and remote's identity is known
    pub(crate) fn verify_remote_key_material(
        &self,
-        remote_material: &[u8],
-        remote_ephemeral_key: &encryption::PublicKey,
+        remote_response: &MaterialExchange,
+        remote_ephemeral_key: &x25519::PublicKey,
    ) -> Result<(), HandshakeError> {
-        if remote_material.len() != identity::SIGNATURE_LENGTH {
-            return Err(HandshakeError::KeyMaterialOfInvalidSize(
-                remote_material.len(),
-            ));
-        }
+        // SAFETY: this function is only called after the local key has already been derived
        let derived_shared_key = self
            .derived_shared_keys
            .as_ref()
            .expect("shared key was not derived!");

+        // if the [client] init message contained non-legacy flag, the associated nonce MUST be present
+        if self.derive_aes256_gcm_siv_key && remote_response.nonce.is_none() {
+            return Err(HandshakeError::MissingNonceForCurrentKey);
+        }
+
        // first decrypt received data
-        let zero_iv = stream_cipher::zero_iv::<GatewayEncryptionAlgorithm>();
-        let decrypted_signature = stream_cipher::decrypt::<GatewayEncryptionAlgorithm>(
-            derived_shared_key.encryption_key(),
-            &zero_iv,
-            remote_material,
-        );
+        let decrypted_signature = derived_shared_key.decrypt_naive(
+            &remote_response.signature_ciphertext,
+            remote_response.nonce.as_deref(),
+        )?;

        // now verify signature itself
        let signature = identity::Signature::from_bytes(&decrypted_signature)
@@ -246,7 +303,7 @@ impl<'a, S> State<'a, S> {
    }

    #[cfg(not(target_arch = "wasm32"))]
-    async fn _receive_handshake_message(&mut self) -> Result<Vec<u8>, HandshakeError>
+    async fn _receive_handshake_message_bytes(&mut self) -> Result<Vec<u8>, HandshakeError>
    where
        S: Stream<Item = WsItem> + Unpin,
    {
@@ -265,7 +322,7 @@ impl<'a, S> State<'a, S> {
    }

    #[cfg(target_arch = "wasm32")]
-    async fn _receive_handshake_message(&mut self) -> Result<Vec<u8>, HandshakeError>
+    async fn _receive_handshake_message_bytes(&mut self) -> Result<Vec<u8>, HandshakeError>
    where
        S: Stream<Item = WsItem> + Unpin,
    {
@@ -278,14 +335,20 @@ impl<'a, S> State<'a, S> {
        }
    }

-    pub(crate) async fn receive_handshake_message(&mut self) -> Result<Vec<u8>, HandshakeError>
+    pub(crate) async fn receive_handshake_message<M>(&mut self) -> Result<M, HandshakeError>
    where
        S: Stream<Item = WsItem> + Unpin,
+        M: HandshakeMessage,
    {
        // TODO: make timeout duration configurable
-        timeout(Duration::from_secs(5), self._receive_handshake_message())
-            .await
-            .map_err(|_| HandshakeError::Timeout)?
+        let bytes = timeout(
+            Duration::from_secs(5),
+            self._receive_handshake_message_bytes(),
+        )
+        .await
+        .map_err(|_| HandshakeError::Timeout)??;
+
+        M::try_from_bytes(&bytes)
    }

    // upon receiving this, the receiver should terminate the handshake
@@ -303,15 +366,30 @@ impl<'a, S> State<'a, S> {
            .map_err(|_| HandshakeError::ClosedStream)
    }

-    pub(crate) async fn send_handshake_data(
+    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
+        }
+    }
+
+    pub(crate) async fn send_handshake_data<M>(
        &mut self,
-        payload: Vec<u8>,
+        inner_message: M,
    ) -> Result<(), HandshakeError>
    where
        S: Sink<WsMessage> + Unpin,
+        M: HandshakeMessage + Any,
    {
-        let handshake_message =
-            types::RegistrationHandshake::new_payload(payload, self.expects_credential_usage);
+        trace!("sending handshake message: {}", type_name::<M>());
+
+        let handshake_message = types::RegistrationHandshake::new_payload(
+            inner_message.into_bytes(),
+            self.request_protocol_version(),
+        );
        self.ws_stream
            .send(WsMessage::Text(handshake_message.try_into().unwrap()))
            .await
@@ -320,7 +398,26 @@ impl<'a, S> State<'a, S> {

    /// Finish the handshake, yielding the derived shared key and implicitly dropping all borrowed
    /// values.
-    pub(crate) fn finalize_handshake(self) -> SharedKeys {
+    pub(crate) fn finalize_handshake(self) -> SharedGatewayKey {
        self.derived_shared_keys.unwrap()
    }
+
+    // If any step along the way failed (that are non-network related),
+    // try to send 'error' message to the remote
+    // party to indicate handshake should be terminated
+    pub(crate) async fn check_for_handshake_processing_error<T>(
+        &mut self,
+        result: Result<T, HandshakeError>,
+    ) -> Result<T, HandshakeError>
+    where
+        S: Sink<WsMessage> + Unpin,
+    {
+        match result {
+            Ok(ok) => Ok(ok),
+            Err(err) => {
+                self.send_handshake_error(err.to_string()).await?;
+                Err(err)
+            }
+        }
+    }
 }
@@ -0,0 +1,98 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{LegacySharedKeys, SharedGatewayKey, SharedKeyUsageError, SharedSymmetricKey};
+use nym_crypto::symmetric::aead::random_nonce;
+use nym_crypto::symmetric::stream_cipher::random_iv;
+use nym_sphinx::params::{GatewayEncryptionAlgorithm, LegacyGatewayEncryptionAlgorithm};
+use rand::thread_rng;
+
+pub trait SymmetricKey {
+    fn random_nonce_or_iv(&self) -> Vec<u8>;
+
+    fn encrypt(
+        &self,
+        plaintext: &[u8],
+        nonce: Option<&[u8]>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError>;
+
+    fn decrypt(
+        &self,
+        ciphertext: &[u8],
+        nonce: Option<&[u8]>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError>;
+}
+
+impl SymmetricKey for SharedGatewayKey {
+    fn random_nonce_or_iv(&self) -> Vec<u8> {
+        self.random_nonce_or_iv()
+    }
+
+    fn encrypt(
+        &self,
+        plaintext: &[u8],
+        nonce: Option<&[u8]>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        self.encrypt(plaintext, nonce)
+    }
+
+    fn decrypt(
+        &self,
+        ciphertext: &[u8],
+        nonce: Option<&[u8]>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        self.decrypt(ciphertext, nonce)
+    }
+}
+
+impl SymmetricKey for SharedSymmetricKey {
+    fn random_nonce_or_iv(&self) -> Vec<u8> {
+        let mut rng = thread_rng();
+
+        random_nonce::<GatewayEncryptionAlgorithm, _>(&mut rng).to_vec()
+    }
+
+    fn encrypt(
+        &self,
+        plaintext: &[u8],
+        nonce: Option<&[u8]>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        let nonce = SharedGatewayKey::validate_aead_nonce(nonce)?;
+        self.encrypt(plaintext, &nonce)
+    }
+
+    fn decrypt(
+        &self,
+        ciphertext: &[u8],
+        nonce: Option<&[u8]>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        let nonce = SharedGatewayKey::validate_aead_nonce(nonce)?;
+        self.decrypt(ciphertext, &nonce)
+    }
+}
+
+impl SymmetricKey for LegacySharedKeys {
+    fn random_nonce_or_iv(&self) -> Vec<u8> {
+        let mut rng = thread_rng();
+
+        random_iv::<LegacyGatewayEncryptionAlgorithm, _>(&mut rng).to_vec()
+    }
+
+    fn encrypt(
+        &self,
+        plaintext: &[u8],
+        nonce: Option<&[u8]>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        let iv = SharedGatewayKey::validate_cipher_iv(nonce)?;
+        Ok(self.encrypt_and_tag(plaintext, iv))
+    }
+
+    fn decrypt(
+        &self,
+        ciphertext: &[u8],
+        nonce: Option<&[u8]>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        let iv = SharedGatewayKey::validate_cipher_iv(nonce)?;
+        self.decrypt_tagged(ciphertext, iv)
+    }
+}
@@ -0,0 +1,241 @@
+// Copyright 2020-2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::registration::handshake::KDF_SALT_LENGTH;
+use crate::shared_key::SharedSymmetricKey;
+use crate::shared_key::{SharedKeyConversionError, SharedKeySize, SharedKeyUsageError};
+use crate::LegacyGatewayMacSize;
+use nym_crypto::generic_array::{
+    typenum::{Sum, Unsigned, U16},
+    GenericArray,
+};
+use nym_crypto::hkdf;
+use nym_crypto::hmac::{compute_keyed_hmac, recompute_keyed_hmac_and_verify_tag};
+use nym_crypto::symmetric::stream_cipher::{self, CipherKey, KeySizeUser, IV};
+use nym_pemstore::traits::PemStorableKey;
+use nym_sphinx::params::{
+    GatewayIntegrityHmacAlgorithm, GatewaySharedKeyHkdfAlgorithm, LegacyGatewayEncryptionAlgorithm,
+};
+use rand::{thread_rng, RngCore};
+use serde::{Deserialize, Serialize};
+use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};
+
+// shared key is as long as the encryption key and the MAC key combined.
+pub type LegacySharedKeySize = Sum<EncryptionKeySize, MacKeySize>;
+
+// we're using 16 byte long key in sphinx, so let's use the same one here
+type MacKeySize = U16;
+type EncryptionKeySize = <LegacyGatewayEncryptionAlgorithm as KeySizeUser>::KeySize;
+
+/// Shared key used when computing MAC for messages exchanged between client and its gateway.
+pub type MacKey = GenericArray<u8, MacKeySize>;
+
+#[derive(Debug, PartialEq, Serialize, Deserialize, Zeroize, ZeroizeOnDrop)]
+pub struct LegacySharedKeys {
+    encryption_key: CipherKey<LegacyGatewayEncryptionAlgorithm>,
+    mac_key: MacKey,
+}
+
+impl LegacySharedKeys {
+    pub fn upgrade(&self) -> (SharedSymmetricKey, Vec<u8>) {
+        let mut rng = thread_rng();
+        let mut salt = vec![0u8; KDF_SALT_LENGTH];
+        rng.fill_bytes(&mut salt);
+
+        let legacy_bytes = Zeroizing::new(self.to_bytes());
+        let okm = hkdf::extract_then_expand::<GatewaySharedKeyHkdfAlgorithm>(
+            Some(&salt),
+            &legacy_bytes,
+            None,
+            SharedKeySize::to_usize(),
+        )
+        .expect("somehow too long okm was provided");
+
+        let key = SharedSymmetricKey::try_from_bytes(&okm)
+            .expect("okm was expanded to incorrect length!");
+        (key, salt)
+    }
+
+    pub fn upgrade_verify(
+        &self,
+        salt: &[u8],
+        expected_digest: &[u8],
+    ) -> Option<SharedSymmetricKey> {
+        let legacy_bytes = Zeroizing::new(self.to_bytes());
+        let okm = hkdf::extract_then_expand::<GatewaySharedKeyHkdfAlgorithm>(
+            Some(salt),
+            &legacy_bytes,
+            None,
+            SharedKeySize::to_usize(),
+        )
+        .expect("somehow too long okm was provided");
+        let key = SharedSymmetricKey::try_from_bytes(&okm)
+            .expect("okm was expanded to incorrect length!");
+        if key.digest() != expected_digest {
+            // no need to zeroize  that key since it's malformed and we won't be using it anyway
+            None
+        } else {
+            Some(key)
+        }
+    }
+
+    pub fn try_from_bytes(bytes: &[u8]) -> Result<Self, SharedKeyConversionError> {
+        if bytes.len() != LegacySharedKeySize::to_usize() {
+            return Err(SharedKeyConversionError::InvalidSharedKeysSize {
+                received: bytes.len(),
+                expected: LegacySharedKeySize::to_usize(),
+            });
+        }
+
+        let encryption_key =
+            GenericArray::clone_from_slice(&bytes[..EncryptionKeySize::to_usize()]);
+        let mac_key = GenericArray::clone_from_slice(&bytes[EncryptionKeySize::to_usize()..]);
+
+        Ok(LegacySharedKeys {
+            encryption_key,
+            mac_key,
+        })
+    }
+
+    /// Encrypts the provided data using the optionally provided initialisation vector,
+    /// or a 0 value if nothing was given.
+    /// It does **NOT** attach any integrity macs on the produced ciphertext
+    pub fn encrypt_without_tagging(
+        &self,
+        data: &[u8],
+        iv: Option<&IV<LegacyGatewayEncryptionAlgorithm>>,
+    ) -> Vec<u8> {
+        match iv {
+            Some(iv) => stream_cipher::encrypt::<LegacyGatewayEncryptionAlgorithm>(
+                self.encryption_key(),
+                iv,
+                data,
+            ),
+            None => {
+                let zero_iv = stream_cipher::zero_iv::<LegacyGatewayEncryptionAlgorithm>();
+                stream_cipher::encrypt::<LegacyGatewayEncryptionAlgorithm>(
+                    self.encryption_key(),
+                    &zero_iv,
+                    data,
+                )
+            }
+        }
+    }
+
+    /// Encrypts the provided data using the optionally provided initialisation vector,
+    /// or a 0 value if nothing was given. Then it computes an integrity mac and concatenates it
+    /// with the previously produced ciphertext.
+    pub fn encrypt_and_tag(
+        &self,
+        data: &[u8],
+        iv: Option<&IV<LegacyGatewayEncryptionAlgorithm>>,
+    ) -> Vec<u8> {
+        let ciphertext = self.encrypt_without_tagging(data, iv);
+        let mac = compute_keyed_hmac::<GatewayIntegrityHmacAlgorithm>(
+            self.mac_key().as_slice(),
+            &ciphertext,
+        );
+
+        mac.into_bytes().into_iter().chain(ciphertext).collect()
+    }
+
+    pub fn decrypt_without_tag(
+        &self,
+        ciphertext: &[u8],
+        iv: Option<&IV<LegacyGatewayEncryptionAlgorithm>>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        let zero_iv = stream_cipher::zero_iv::<LegacyGatewayEncryptionAlgorithm>();
+        let iv = iv.unwrap_or(&zero_iv);
+        Ok(stream_cipher::decrypt::<LegacyGatewayEncryptionAlgorithm>(
+            self.encryption_key(),
+            iv,
+            ciphertext,
+        ))
+    }
+
+    pub fn decrypt_tagged(
+        &self,
+        enc_data: &[u8],
+        iv: Option<&IV<LegacyGatewayEncryptionAlgorithm>>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        let mac_size = LegacyGatewayMacSize::to_usize();
+        if enc_data.len() < mac_size {
+            return Err(SharedKeyUsageError::TooShortRequest);
+        }
+
+        let mac_tag = &enc_data[..mac_size];
+        let message_bytes = &enc_data[mac_size..];
+
+        if !recompute_keyed_hmac_and_verify_tag::<GatewayIntegrityHmacAlgorithm>(
+            self.mac_key().as_slice(),
+            message_bytes,
+            mac_tag,
+        ) {
+            return Err(SharedKeyUsageError::InvalidMac);
+        }
+
+        // couldn't have made the first borrow mutable as you can't have an immutable borrow
+        // together with a mutable one
+        let mut message_bytes_mut = message_bytes.to_vec();
+
+        let zero_iv = stream_cipher::zero_iv::<LegacyGatewayEncryptionAlgorithm>();
+        let iv = iv.unwrap_or(&zero_iv);
+        stream_cipher::decrypt_in_place::<LegacyGatewayEncryptionAlgorithm>(
+            self.encryption_key(),
+            iv,
+            &mut message_bytes_mut,
+        );
+        Ok(message_bytes_mut)
+    }
+
+    pub fn encryption_key(&self) -> &CipherKey<LegacyGatewayEncryptionAlgorithm> {
+        &self.encryption_key
+    }
+
+    pub fn mac_key(&self) -> &MacKey {
+        &self.mac_key
+    }
+
+    pub fn to_bytes(&self) -> Vec<u8> {
+        self.encryption_key
+            .iter()
+            .copied()
+            .chain(self.mac_key.iter().copied())
+            .collect()
+    }
+
+    pub fn try_from_base58_string<S: Into<String>>(
+        val: S,
+    ) -> Result<Self, SharedKeyConversionError> {
+        let decoded = bs58::decode(val.into()).into_vec()?;
+        LegacySharedKeys::try_from_bytes(&decoded)
+    }
+
+    pub fn to_base58_string(&self) -> String {
+        bs58::encode(self.to_bytes()).into_string()
+    }
+}
+
+impl From<LegacySharedKeys> for String {
+    fn from(keys: LegacySharedKeys) -> Self {
+        keys.to_base58_string()
+    }
+}
+
+impl PemStorableKey for LegacySharedKeys {
+    type Error = SharedKeyConversionError;
+
+    fn pem_type() -> &'static str {
+        // TODO: If common\nymsphinx\params\src\lib::GatewayIntegrityHmacAlgorithm changes
+        // the pem type needs updating!
+        "AES-128-CTR + HMAC-BLAKE3 GATEWAY SHARED KEYS"
+    }
+
+    fn to_bytes(&self) -> Vec<u8> {
+        self.to_bytes()
+    }
+
+    fn from_bytes(bytes: &[u8]) -> Result<Self, Self::Error> {
+        Self::try_from_bytes(bytes)
+    }
+}
@@ -0,0 +1,304 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_crypto::blake3;
+use nym_crypto::crypto_hash::compute_digest;
+use nym_crypto::generic_array::{typenum::Unsigned, GenericArray};
+use nym_crypto::symmetric::aead::{
+    self, nonce_size, random_nonce, AeadError, AeadKey, KeySizeUser, Nonce,
+};
+use nym_crypto::symmetric::stream_cipher::{iv_size, random_iv, IV};
+use nym_pemstore::traits::PemStorableKey;
+use nym_sphinx::params::{GatewayEncryptionAlgorithm, LegacyGatewayEncryptionAlgorithm};
+use rand::thread_rng;
+use serde::{Deserialize, Serialize};
+use thiserror::Error;
+use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};
+
+pub use legacy::LegacySharedKeys;
+
+pub mod helpers;
+pub mod legacy;
+
+pub type SharedKeySize = <GatewayEncryptionAlgorithm as KeySizeUser>::KeySize;
+
+#[derive(Debug, PartialEq, Zeroize, ZeroizeOnDrop)]
+pub enum SharedGatewayKey {
+    Current(SharedSymmetricKey),
+    Legacy(LegacySharedKeys),
+}
+
+impl SharedGatewayKey {
+    pub fn is_legacy(&self) -> bool {
+        matches!(self, SharedGatewayKey::Legacy(..))
+    }
+
+    pub fn aes128_ctr_hmac_bs58(&self) -> Option<Zeroizing<String>> {
+        match self {
+            SharedGatewayKey::Current(_) => None,
+            SharedGatewayKey::Legacy(key) => Some(Zeroizing::new(key.to_base58_string())),
+        }
+    }
+
+    pub fn aes256_gcm_siv(&self) -> Option<Zeroizing<Vec<u8>>> {
+        match self {
+            SharedGatewayKey::Current(key) => Some(Zeroizing::new(key.to_bytes())),
+            SharedGatewayKey::Legacy(_) => None,
+        }
+    }
+
+    pub fn unwrap_legacy(&self) -> &LegacySharedKeys {
+        match self {
+            SharedGatewayKey::Current(_) => panic!("expected legacy key"),
+            SharedGatewayKey::Legacy(key) => key,
+        }
+    }
+
+    pub fn random_nonce_or_iv(&self) -> Vec<u8> {
+        let mut rng = thread_rng();
+
+        if self.is_legacy() {
+            random_iv::<LegacyGatewayEncryptionAlgorithm, _>(&mut rng).to_vec()
+        } else {
+            random_nonce::<GatewayEncryptionAlgorithm, _>(&mut rng).to_vec()
+        }
+    }
+
+    pub fn random_nonce_or_zero_iv(&self) -> Option<Vec<u8>> {
+        if self.is_legacy() {
+            None
+        } else {
+            let mut rng = thread_rng();
+            Some(random_nonce::<GatewayEncryptionAlgorithm, _>(&mut rng).to_vec())
+        }
+    }
+
+    pub fn nonce_size(&self) -> usize {
+        match self {
+            SharedGatewayKey::Current(_) => nonce_size::<GatewayEncryptionAlgorithm>(),
+            SharedGatewayKey::Legacy(_) => iv_size::<LegacyGatewayEncryptionAlgorithm>(),
+        }
+    }
+}
+
+impl From<LegacySharedKeys> for SharedGatewayKey {
+    fn from(keys: LegacySharedKeys) -> Self {
+        SharedGatewayKey::Legacy(keys)
+    }
+}
+
+impl From<SharedSymmetricKey> for SharedGatewayKey {
+    fn from(keys: SharedSymmetricKey) -> Self {
+        SharedGatewayKey::Current(keys)
+    }
+}
+
+#[derive(Debug, Error)]
+pub enum SharedKeyUsageError {
+    #[error("the request is too short")]
+    TooShortRequest,
+
+    #[error("provided MAC is invalid")]
+    InvalidMac,
+
+    #[error("the provided nonce (or legacy IV) did not have the expected length")]
+    MalformedNonce,
+
+    #[error("did not provide a valid nonce for aead encryption")]
+    MissingAeadNonce,
+
+    #[error("failed to either encrypt or decrypt provided message")]
+    AeadFailure(#[from] AeadError),
+}
+
+impl SharedGatewayKey {
+    fn validate_aead_nonce(
+        raw: Option<&[u8]>,
+    ) -> Result<Nonce<GatewayEncryptionAlgorithm>, SharedKeyUsageError> {
+        let Some(raw) = raw else {
+            return Err(SharedKeyUsageError::MissingAeadNonce);
+        };
+        if raw.len() != nonce_size::<GatewayEncryptionAlgorithm>() {
+            return Err(SharedKeyUsageError::MalformedNonce);
+        }
+        Ok(Nonce::<GatewayEncryptionAlgorithm>::clone_from_slice(raw))
+    }
+
+    fn validate_cipher_iv(
+        raw: Option<&[u8]>,
+    ) -> Result<Option<&IV<LegacyGatewayEncryptionAlgorithm>>, SharedKeyUsageError> {
+        let Some(raw) = raw else { return Ok(None) };
+        let iv = if raw.is_empty() {
+            None
+        } else {
+            if raw.len() != iv_size::<LegacyGatewayEncryptionAlgorithm>() {
+                return Err(SharedKeyUsageError::MalformedNonce);
+            }
+            Some(IV::<LegacyGatewayEncryptionAlgorithm>::from_slice(raw))
+        };
+        Ok(iv)
+    }
+
+    pub fn encrypt(
+        &self,
+        plaintext: &[u8],
+        // the best common denominator for converting into 'IV' and 'Nonce' types
+        raw_nonce: Option<&[u8]>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        match self {
+            SharedGatewayKey::Current(aes_gcm_siv) => {
+                let nonce = Self::validate_aead_nonce(raw_nonce)?;
+                aes_gcm_siv.encrypt(plaintext, &nonce)
+            }
+            SharedGatewayKey::Legacy(aes_ctr) => {
+                let iv = Self::validate_cipher_iv(raw_nonce)?;
+                Ok(aes_ctr.encrypt_and_tag(plaintext, iv))
+            }
+        }
+    }
+
+    pub fn decrypt(
+        &self,
+        ciphertext: &[u8],
+        // the best common denominator for converting into 'IV' and 'Nonce' types
+        raw_nonce: Option<&[u8]>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        match self {
+            SharedGatewayKey::Current(aes_gcm_siv) => {
+                let nonce = Self::validate_aead_nonce(raw_nonce)?;
+                aes_gcm_siv.decrypt(ciphertext, &nonce)
+            }
+            SharedGatewayKey::Legacy(aes_ctr) => {
+                let iv = Self::validate_cipher_iv(raw_nonce)?;
+                aes_ctr.decrypt_tagged(ciphertext, iv)
+            }
+        }
+    }
+
+    // for the legacy keys do not use integrity MAC
+    pub fn encrypt_naive(
+        &self,
+        plaintext: &[u8],
+        // the best common denominator for converting into 'IV' and 'Nonce' types
+        raw_nonce: Option<&[u8]>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        match self {
+            SharedGatewayKey::Current(aes_gcm_siv) => {
+                let nonce = Self::validate_aead_nonce(raw_nonce)?;
+                aes_gcm_siv.encrypt(plaintext, &nonce)
+            }
+            SharedGatewayKey::Legacy(aes_ctr) => {
+                let iv = Self::validate_cipher_iv(raw_nonce)?;
+                Ok(aes_ctr.encrypt_without_tagging(plaintext, iv))
+            }
+        }
+    }
+
+    // for the legacy keys do not use integrity MAC
+    pub fn decrypt_naive(
+        &self,
+        ciphertext: &[u8],
+        // the best common denominator for converting into 'IV' and 'Nonce' types
+        raw_nonce: Option<&[u8]>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        match self {
+            SharedGatewayKey::Current(aes_gcm_siv) => {
+                let nonce = Self::validate_aead_nonce(raw_nonce)?;
+                aes_gcm_siv.decrypt(ciphertext, &nonce)
+            }
+            SharedGatewayKey::Legacy(aes_ctr) => {
+                let iv = Self::validate_cipher_iv(raw_nonce)?;
+                aes_ctr.decrypt_without_tag(ciphertext, iv)
+            }
+        }
+    }
+}
+
+#[derive(Debug, PartialEq, Serialize, Deserialize, Zeroize, ZeroizeOnDrop)]
+pub struct SharedSymmetricKey(AeadKey<GatewayEncryptionAlgorithm>);
+
+type KeySize = <GatewayEncryptionAlgorithm as KeySizeUser>::KeySize;
+
+#[derive(Debug, Clone, Copy, Error)]
+pub enum SharedKeyConversionError {
+    #[error("the string representation of the shared key was malformed: {0}")]
+    DecodeError(#[from] bs58::decode::Error),
+    #[error(
+        "the received shared keys had invalid size. Got: {received}, but expected: {expected}"
+    )]
+    InvalidSharedKeysSize { received: usize, expected: usize },
+}
+
+impl SharedSymmetricKey {
+    pub fn try_from_bytes(bytes: &[u8]) -> Result<Self, SharedKeyConversionError> {
+        if bytes.len() != KeySize::to_usize() {
+            return Err(SharedKeyConversionError::InvalidSharedKeysSize {
+                received: bytes.len(),
+                expected: KeySize::to_usize(),
+            });
+        }
+
+        Ok(SharedSymmetricKey(GenericArray::clone_from_slice(bytes)))
+    }
+
+    pub fn zeroizing_clone(&self) -> Zeroizing<Self> {
+        Zeroizing::new(SharedSymmetricKey(self.0))
+    }
+
+    pub fn digest(&self) -> Vec<u8> {
+        compute_digest::<blake3::Hasher>(self.as_bytes()).to_vec()
+    }
+
+    pub fn as_bytes(&self) -> &[u8] {
+        self.0.as_slice()
+    }
+
+    pub fn to_bytes(&self) -> Vec<u8> {
+        self.0.iter().copied().collect()
+    }
+
+    pub fn try_from_base58_string<S: Into<String>>(
+        val: S,
+    ) -> Result<Self, SharedKeyConversionError> {
+        let bs58_str = Zeroizing::new(val.into());
+        let decoded = Zeroizing::new(bs58::decode(bs58_str).into_vec()?);
+        Self::try_from_bytes(&decoded)
+    }
+
+    pub fn to_base58_string(&self) -> String {
+        let bytes = Zeroizing::new(self.to_bytes());
+        bs58::encode(bytes).into_string()
+    }
+
+    pub fn encrypt(
+        &self,
+        plaintext: &[u8],
+        nonce: &Nonce<GatewayEncryptionAlgorithm>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        aead::encrypt::<GatewayEncryptionAlgorithm>(&self.0, nonce, plaintext).map_err(Into::into)
+    }
+
+    pub fn decrypt(
+        &self,
+        ciphertext: &[u8],
+        nonce: &Nonce<GatewayEncryptionAlgorithm>,
+    ) -> Result<Vec<u8>, SharedKeyUsageError> {
+        aead::decrypt::<GatewayEncryptionAlgorithm>(&self.0, nonce, ciphertext).map_err(Into::into)
+    }
+}
+
+impl PemStorableKey for SharedSymmetricKey {
+    type Error = SharedKeyConversionError;
+
+    fn pem_type() -> &'static str {
+        "AES-256-GCM-SIV GATEWAY SHARED KEY"
+    }
+
+    fn to_bytes(&self) -> Vec<u8> {
+        self.to_bytes()
+    }
+
+    fn from_bytes(bytes: &[u8]) -> Result<Self, Self::Error> {
+        Self::try_from_bytes(bytes)
+    }
+}
@@ -1,511 +0,0 @@
-// Copyright 2020-2024 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0
-
-use crate::authentication::encrypted_address::EncryptedAddressBytes;
-use crate::iv::{IVConversionError, IV};
-use crate::models::CredentialSpendingRequest;
-use crate::registration::handshake::SharedKeys;
-use crate::{GatewayMacSize, CURRENT_PROTOCOL_VERSION, INITIAL_PROTOCOL_VERSION};
-use nym_credentials::ecash::bandwidth::CredentialSpendingData;
-use nym_credentials_interface::CompactEcashError;
-use nym_crypto::generic_array::typenum::Unsigned;
-use nym_crypto::hmac::recompute_keyed_hmac_and_verify_tag;
-use nym_crypto::symmetric::stream_cipher;
-use nym_sphinx::addressing::nodes::NymNodeRoutingAddressError;
-use nym_sphinx::forwarding::packet::{MixPacket, MixPacketFormattingError};
-use nym_sphinx::params::packet_sizes::PacketSize;
-use nym_sphinx::params::{GatewayEncryptionAlgorithm, GatewayIntegrityHmacAlgorithm};
-use nym_sphinx::DestinationAddressBytes;
-use serde::{Deserialize, Serialize};
-use tracing::log::error;
-
-use std::str::FromStr;
-use std::string::FromUtf8Error;
-use thiserror::Error;
-use tungstenite::protocol::Message;
-
-#[derive(Serialize, Deserialize, Debug)]
-#[serde(tag = "type", rename_all = "camelCase")]
-pub enum RegistrationHandshake {
-    HandshakePayload {
-        #[serde(default)]
-        protocol_version: Option<u8>,
-        data: Vec<u8>,
-    },
-    HandshakeError {
-        message: String,
-    },
-}
-
-impl RegistrationHandshake {
-    pub fn new_payload(data: Vec<u8>, will_use_credentials: bool) -> Self {
-        // if we're not going to be using credentials, advertise lower protocol version to allow connection
-        // to wider range of gateways
-        let protocol_version = if will_use_credentials {
-            Some(CURRENT_PROTOCOL_VERSION)
-        } else {
-            Some(INITIAL_PROTOCOL_VERSION)
-        };
-
-        RegistrationHandshake::HandshakePayload {
-            protocol_version,
-            data,
-        }
-    }
-
-    pub fn new_error<S: Into<String>>(message: S) -> Self {
-        RegistrationHandshake::HandshakeError {
-            message: message.into(),
-        }
-    }
-}
-
-impl FromStr for RegistrationHandshake {
-    type Err = serde_json::Error;
-
-    fn from_str(s: &str) -> Result<Self, Self::Err> {
-        serde_json::from_str(s)
-    }
-}
-
-impl TryFrom<String> for RegistrationHandshake {
-    type Error = serde_json::Error;
-
-    fn try_from(msg: String) -> Result<Self, serde_json::Error> {
-        msg.parse()
-    }
-}
-
-impl TryInto<String> for RegistrationHandshake {
-    type Error = serde_json::Error;
-
-    fn try_into(self) -> Result<String, serde_json::Error> {
-        serde_json::to_string(&self)
-    }
-}
-
-// specific errors (that should not be nested!!) for clients to match on
-#[derive(Debug, Copy, Clone, Error, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum SimpleGatewayRequestsError {
-    #[error("insufficient bandwidth available to process the request. required: {required}B, available: {available}B")]
-    OutOfBandwidth { required: i64, available: i64 },
-
-    #[error("the provided ticket has already been spent before at this gateway")]
-    TicketReplay,
-}
-
-impl SimpleGatewayRequestsError {
-    pub fn is_ticket_replay(&self) -> bool {
-        matches!(self, SimpleGatewayRequestsError::TicketReplay)
-    }
-}
-
-#[derive(Debug, Error)]
-pub enum GatewayRequestsError {
-    #[error("the request is too short")]
-    TooShortRequest,
-
-    #[error("provided MAC is invalid")]
-    InvalidMac,
-
-    #[error("Provided bandwidth IV is malformed: {0}")]
-    MalformedIV(#[from] IVConversionError),
-
-    #[error("address field was incorrectly encoded: {source}")]
-    IncorrectlyEncodedAddress {
-        #[from]
-        source: NymNodeRoutingAddressError,
-    },
-
-    #[error("received request had invalid size. (actual: {0}, but expected one of: {} (ACK), {} (REGULAR), {}, {}, {} (EXTENDED))",
-        PacketSize::AckPacket.size(),
-        PacketSize::RegularPacket.size(),
-        PacketSize::ExtendedPacket8.size(),
-        PacketSize::ExtendedPacket16.size(),
-        PacketSize::ExtendedPacket32.size())
-    ]
-    RequestOfInvalidSize(usize),
-
-    #[error("received sphinx packet was malformed")]
-    MalformedSphinxPacket,
-
-    #[error("the received encrypted data was malformed")]
-    MalformedEncryption,
-
-    #[error("provided packet mode is invalid")]
-    InvalidPacketMode,
-
-    #[error("provided mix packet was malformed: {source}")]
-    InvalidMixPacket {
-        #[from]
-        source: MixPacketFormattingError,
-    },
-
-    #[error("failed to deserialize provided credential: {0}")]
-    EcashCredentialDeserializationFailure(#[from] CompactEcashError),
-
-    #[error("failed to deserialize provided credential: EOF")]
-    CredentialDeserializationFailureEOF,
-
-    #[error("failed to deserialize provided credential: malformed string: {0}")]
-    CredentialDeserializationFailureMalformedString(#[from] FromUtf8Error),
-
-    #[error("the provided [v1] credential has invalid number of parameters - {0}")]
-    InvalidNumberOfEmbededParameters(u32),
-
-    // variant to catch legacy errors
-    #[error("{0}")]
-    Other(String),
-}
-
-#[derive(Serialize, Deserialize, Debug)]
-#[serde(tag = "type", rename_all = "camelCase")]
-pub enum ClientControlRequest {
-    // TODO: should this also contain a MAC considering that at this point we already
-    // have the shared key derived?
-    Authenticate {
-        #[serde(default)]
-        protocol_version: Option<u8>,
-        address: String,
-        enc_address: String,
-        iv: String,
-    },
-    #[serde(alias = "handshakePayload")]
-    RegisterHandshakeInitRequest {
-        #[serde(default)]
-        protocol_version: Option<u8>,
-        data: Vec<u8>,
-    },
-    BandwidthCredential {
-        enc_credential: Vec<u8>,
-        iv: Vec<u8>,
-    },
-    BandwidthCredentialV2 {
-        enc_credential: Vec<u8>,
-        iv: Vec<u8>,
-    },
-    EcashCredential {
-        enc_credential: Vec<u8>,
-        iv: Vec<u8>,
-    },
-    ClaimFreeTestnetBandwidth,
-}
-
-impl ClientControlRequest {
-    pub fn new_authenticate(
-        address: DestinationAddressBytes,
-        enc_address: EncryptedAddressBytes,
-        iv: IV,
-        uses_credentials: bool,
-    ) -> Self {
-        // if we're not going to be using credentials, advertise lower protocol version to allow connection
-        // to wider range of gateways
-        let protocol_version = if uses_credentials {
-            Some(CURRENT_PROTOCOL_VERSION)
-        } else {
-            Some(INITIAL_PROTOCOL_VERSION)
-        };
-
-        ClientControlRequest::Authenticate {
-            protocol_version,
-            address: address.as_base58_string(),
-            enc_address: enc_address.to_base58_string(),
-            iv: iv.to_base58_string(),
-        }
-    }
-
-    pub fn name(&self) -> String {
-        match self {
-            ClientControlRequest::Authenticate { .. } => "Authenticate".to_string(),
-            ClientControlRequest::RegisterHandshakeInitRequest { .. } => {
-                "RegisterHandshakeInitRequest".to_string()
-            }
-            ClientControlRequest::BandwidthCredential { .. } => "BandwidthCredential".to_string(),
-            ClientControlRequest::BandwidthCredentialV2 { .. } => {
-                "BandwidthCredentialV2".to_string()
-            }
-            ClientControlRequest::EcashCredential { .. } => "EcashCredential".to_string(),
-            ClientControlRequest::ClaimFreeTestnetBandwidth => {
-                "ClaimFreeTestnetBandwidth".to_string()
-            }
-        }
-    }
-
-    pub fn new_enc_ecash_credential(
-        credential: CredentialSpendingData,
-        shared_key: &SharedKeys,
-        iv: IV,
-    ) -> Self {
-        let cred = CredentialSpendingRequest::new(credential);
-        let serialized_credential = cred.to_bytes();
-        let enc_credential = shared_key.encrypt_and_tag(&serialized_credential, Some(iv.inner()));
-
-        ClientControlRequest::EcashCredential {
-            enc_credential,
-            iv: iv.to_bytes(),
-        }
-    }
-
-    pub fn try_from_enc_ecash_credential(
-        enc_credential: Vec<u8>,
-        shared_key: &SharedKeys,
-        iv: Vec<u8>,
-    ) -> Result<CredentialSpendingRequest, GatewayRequestsError> {
-        let iv = IV::try_from_bytes(&iv)?;
-        let credential_bytes = shared_key.decrypt_tagged(&enc_credential, Some(iv.inner()))?;
-        CredentialSpendingRequest::try_from_bytes(credential_bytes.as_slice())
-            .map_err(|_| GatewayRequestsError::MalformedEncryption)
-    }
-}
-
-impl From<ClientControlRequest> for Message {
-    fn from(req: ClientControlRequest) -> Self {
-        // it should be safe to call `unwrap` here as the message is generated by the server
-        // so if it fails (and consequently panics) it's a bug that should be resolved
-        let str_req = serde_json::to_string(&req).unwrap();
-        Message::Text(str_req)
-    }
-}
-
-impl TryFrom<String> for ClientControlRequest {
-    type Error = serde_json::Error;
-
-    fn try_from(msg: String) -> Result<Self, Self::Error> {
-        serde_json::from_str(&msg)
-    }
-}
-
-impl TryInto<String> for ClientControlRequest {
-    type Error = serde_json::Error;
-
-    fn try_into(self) -> Result<String, Self::Error> {
-        serde_json::to_string(&self)
-    }
-}
-
-#[derive(Serialize, Deserialize, Debug)]
-#[serde(tag = "type", rename_all = "camelCase")]
-pub enum ServerResponse {
-    Authenticate {
-        #[serde(default)]
-        protocol_version: Option<u8>,
-        status: bool,
-        bandwidth_remaining: i64,
-    },
-    Register {
-        #[serde(default)]
-        protocol_version: Option<u8>,
-        status: bool,
-    },
-    Bandwidth {
-        available_total: i64,
-    },
-    Send {
-        remaining_bandwidth: i64,
-    },
-    // Generic error
-    Error {
-        message: String,
-    },
-    // Specific typed errors
-    // so that clients could match on this variant without doing naive string matching
-    TypedError {
-        error: SimpleGatewayRequestsError,
-    },
-}
-
-impl ServerResponse {
-    pub fn name(&self) -> String {
-        match self {
-            ServerResponse::Authenticate { .. } => "Authenticate".to_string(),
-            ServerResponse::Register { .. } => "Register".to_string(),
-            ServerResponse::Bandwidth { .. } => "Bandwidth".to_string(),
-            ServerResponse::Send { .. } => "Send".to_string(),
-            ServerResponse::Error { .. } => "Error".to_string(),
-            ServerResponse::TypedError { .. } => "TypedError".to_string(),
-        }
-    }
-    pub fn new_error<S: Into<String>>(msg: S) -> Self {
-        ServerResponse::Error {
-            message: msg.into(),
-        }
-    }
-
-    pub fn is_error(&self) -> bool {
-        matches!(self, ServerResponse::Error { .. })
-    }
-
-    pub fn implies_successful_authentication(&self) -> bool {
-        match self {
-            ServerResponse::Authenticate { status, .. } => *status,
-            ServerResponse::Register { status, .. } => *status,
-            _ => false,
-        }
-    }
-}
-
-impl From<ServerResponse> for Message {
-    fn from(res: ServerResponse) -> Self {
-        // it should be safe to call `unwrap` here as the message is generated by the server
-        // so if it fails (and consequently panics) it's a bug that should be resolved
-        let str_res = serde_json::to_string(&res).unwrap();
-        Message::Text(str_res)
-    }
-}
-
-impl TryFrom<String> for ServerResponse {
-    type Error = serde_json::Error;
-
-    fn try_from(msg: String) -> Result<Self, serde_json::Error> {
-        serde_json::from_str(&msg)
-    }
-}
-
-pub enum BinaryRequest {
-    ForwardSphinx(MixPacket),
-}
-
-// Right now the only valid `BinaryRequest` is a request to forward a sphinx packet.
-// It is encrypted using the derived shared key between client and the gateway. Thanks to
-// randomness inside the sphinx packet themselves (even via the same route), the 0s IV can be used here.
-// HOWEVER, NOTE: If we introduced another 'BinaryRequest', we must carefully examine if a 0s IV
-// would work there.
-impl BinaryRequest {
-    pub fn try_from_encrypted_tagged_bytes(
-        raw_req: Vec<u8>,
-        shared_keys: &SharedKeys,
-    ) -> Result<Self, GatewayRequestsError> {
-        let message_bytes = &shared_keys.decrypt_tagged(&raw_req, None)?;
-
-        // right now there's only a single option possible which significantly simplifies the logic
-        // if we decided to allow for more 'binary' messages, the API wouldn't need to change.
-        let mix_packet = MixPacket::try_from_bytes(message_bytes)?;
-        Ok(BinaryRequest::ForwardSphinx(mix_packet))
-    }
-
-    pub fn into_encrypted_tagged_bytes(self, shared_key: &SharedKeys) -> Vec<u8> {
-        match self {
-            BinaryRequest::ForwardSphinx(mix_packet) => {
-                let forwarding_data = match mix_packet.into_bytes() {
-                    Ok(mix_packet) => mix_packet,
-                    Err(e) => {
-                        error!("Could not convert packet to bytes: {e}");
-                        return vec![];
-                    }
-                };
-
-                // TODO: it could be theoretically slightly more efficient if the data wasn't taken
-                // by reference because then it makes a copy for encryption rather than do it in place
-                shared_key.encrypt_and_tag(&forwarding_data, None)
-            }
-        }
-    }
-
-    // TODO: this will be encrypted, etc.
-    pub fn new_forward_request(mix_packet: MixPacket) -> BinaryRequest {
-        BinaryRequest::ForwardSphinx(mix_packet)
-    }
-
-    pub fn into_ws_message(self, shared_key: &SharedKeys) -> Message {
-        Message::Binary(self.into_encrypted_tagged_bytes(shared_key))
-    }
-}
-
-// Introduced for consistency sake
-pub enum BinaryResponse {
-    PushedMixMessage(Vec<u8>),
-}
-
-impl BinaryResponse {
-    pub fn try_from_encrypted_tagged_bytes(
-        raw_req: Vec<u8>,
-        shared_keys: &SharedKeys,
-    ) -> Result<Self, GatewayRequestsError> {
-        let mac_size = GatewayMacSize::to_usize();
-        if raw_req.len() < mac_size {
-            return Err(GatewayRequestsError::TooShortRequest);
-        }
-
-        let mac_tag = &raw_req[..mac_size];
-        let message_bytes = &raw_req[mac_size..];
-
-        if !recompute_keyed_hmac_and_verify_tag::<GatewayIntegrityHmacAlgorithm>(
-            shared_keys.mac_key().as_slice(),
-            message_bytes,
-            mac_tag,
-        ) {
-            return Err(GatewayRequestsError::InvalidMac);
-        }
-
-        let zero_iv = stream_cipher::zero_iv::<GatewayEncryptionAlgorithm>();
-        let plaintext = stream_cipher::decrypt::<GatewayEncryptionAlgorithm>(
-            shared_keys.encryption_key(),
-            &zero_iv,
-            message_bytes,
-        );
-
-        Ok(BinaryResponse::PushedMixMessage(plaintext))
-    }
-
-    pub fn into_encrypted_tagged_bytes(self, shared_key: &SharedKeys) -> Vec<u8> {
-        match self {
-            // TODO: it could be theoretically slightly more efficient if the data wasn't taken
-            // by reference because then it makes a copy for encryption rather than do it in place
-            BinaryResponse::PushedMixMessage(message) => shared_key.encrypt_and_tag(&message, None),
-        }
-    }
-
-    pub fn new_pushed_mix_message(msg: Vec<u8>) -> Self {
-        BinaryResponse::PushedMixMessage(msg)
-    }
-
-    pub fn into_ws_message(self, shared_key: &SharedKeys) -> Message {
-        Message::Binary(self.into_encrypted_tagged_bytes(shared_key))
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn handshake_payload_can_be_deserialized_into_register_handshake_init_request() {
-        let handshake_data = vec![1, 2, 3, 4, 5, 6];
-        let handshake_payload_with_protocol = RegistrationHandshake::HandshakePayload {
-            protocol_version: Some(42),
-            data: handshake_data.clone(),
-        };
-        let serialized = serde_json::to_string(&handshake_payload_with_protocol).unwrap();
-        let deserialized = ClientControlRequest::try_from(serialized).unwrap();
-
-        match deserialized {
-            ClientControlRequest::RegisterHandshakeInitRequest {
-                protocol_version,
-                data,
-            } => {
-                assert_eq!(protocol_version, Some(42));
-                assert_eq!(data, handshake_data)
-            }
-            _ => unreachable!("this branch shouldn't have been reached!"),
-        }
-
-        let handshake_payload_without_protocol = RegistrationHandshake::HandshakePayload {
-            protocol_version: None,
-            data: handshake_data.clone(),
-        };
-        let serialized = serde_json::to_string(&handshake_payload_without_protocol).unwrap();
-        let deserialized = ClientControlRequest::try_from(serialized).unwrap();
-
-        match deserialized {
-            ClientControlRequest::RegisterHandshakeInitRequest {
-                protocol_version,
-                data,
-            } => {
-                assert!(protocol_version.is_none());
-                assert_eq!(data, handshake_data)
-            }
-            _ => unreachable!("this branch shouldn't have been reached!"),
-        }
-    }
-}
@@ -0,0 +1,78 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::types::helpers::BinaryData;
+use crate::{GatewayRequestsError, SharedGatewayKey};
+use nym_sphinx::forwarding::packet::MixPacket;
+use strum::FromRepr;
+use tungstenite::Message;
+
+// in legacy mode requests use zero IV without
+#[non_exhaustive]
+pub enum BinaryRequest {
+    ForwardSphinx { packet: MixPacket },
+}
+
+#[repr(u8)]
+#[derive(Debug, Clone, Copy, FromRepr, PartialEq)]
+#[non_exhaustive]
+pub enum BinaryRequestKind {
+    ForwardSphinx = 1,
+}
+
+// Right now the only valid `BinaryRequest` is a request to forward a sphinx packet.
+// It is encrypted using the derived shared key between client and the gateway. Thanks to
+// randomness inside the sphinx packet themselves (even via the same route), the 0s IV can be used here.
+// HOWEVER, NOTE: If we introduced another 'BinaryRequest', we must carefully examine if a 0s IV
+// would work there.
+impl BinaryRequest {
+    pub fn kind(&self) -> BinaryRequestKind {
+        match self {
+            BinaryRequest::ForwardSphinx { .. } => BinaryRequestKind::ForwardSphinx,
+        }
+    }
+
+    pub fn from_plaintext(
+        kind: BinaryRequestKind,
+        plaintext: &[u8],
+    ) -> Result<Self, GatewayRequestsError> {
+        match kind {
+            BinaryRequestKind::ForwardSphinx => {
+                let packet = MixPacket::try_from_bytes(plaintext)?;
+                Ok(BinaryRequest::ForwardSphinx { packet })
+            }
+        }
+    }
+
+    pub fn try_from_encrypted_tagged_bytes(
+        bytes: Vec<u8>,
+        shared_key: &SharedGatewayKey,
+    ) -> Result<Self, GatewayRequestsError> {
+        BinaryData::from_raw(&bytes, shared_key)?.into_request(shared_key)
+    }
+
+    pub fn into_encrypted_tagged_bytes(
+        self,
+        shared_key: &SharedGatewayKey,
+    ) -> Result<Vec<u8>, GatewayRequestsError> {
+        let kind = self.kind();
+
+        let plaintext = match self {
+            BinaryRequest::ForwardSphinx { packet } => packet.into_bytes()?,
+        };
+
+        BinaryData::make_encrypted_blob(kind as u8, &plaintext, shared_key)
+    }
+
+    pub fn into_ws_message(
+        self,
+        shared_key: &SharedGatewayKey,
+    ) -> Result<Message, GatewayRequestsError> {
+        // all variants are currently encrypted
+        let blob = match self {
+            BinaryRequest::ForwardSphinx { .. } => self.into_encrypted_tagged_bytes(shared_key)?,
+        };
+
+        Ok(Message::Binary(blob))
+    }
+}
@@ -0,0 +1,72 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::types::helpers::BinaryData;
+use crate::{GatewayRequestsError, SharedGatewayKey};
+use strum::FromRepr;
+use tungstenite::Message;
+
+#[non_exhaustive]
+pub enum BinaryResponse {
+    PushedMixMessage { message: Vec<u8> },
+}
+
+#[repr(u8)]
+#[derive(Debug, Clone, Copy, FromRepr, PartialEq)]
+#[non_exhaustive]
+pub enum BinaryResponseKind {
+    PushedMixMessage = 1,
+}
+
+impl BinaryResponse {
+    pub fn kind(&self) -> BinaryResponseKind {
+        match self {
+            BinaryResponse::PushedMixMessage { .. } => BinaryResponseKind::PushedMixMessage,
+        }
+    }
+
+    pub fn from_plaintext(
+        kind: BinaryResponseKind,
+        plaintext: &[u8],
+    ) -> Result<Self, GatewayRequestsError> {
+        match kind {
+            BinaryResponseKind::PushedMixMessage => Ok(BinaryResponse::PushedMixMessage {
+                message: plaintext.to_vec(),
+            }),
+        }
+    }
+
+    pub fn try_from_encrypted_tagged_bytes(
+        bytes: Vec<u8>,
+        shared_key: &SharedGatewayKey,
+    ) -> Result<Self, GatewayRequestsError> {
+        BinaryData::from_raw(&bytes, shared_key)?.into_response(shared_key)
+    }
+
+    pub fn into_encrypted_tagged_bytes(
+        self,
+        shared_key: &SharedGatewayKey,
+    ) -> Result<Vec<u8>, GatewayRequestsError> {
+        let kind = self.kind();
+
+        let plaintext = match self {
+            BinaryResponse::PushedMixMessage { message } => message,
+        };
+
+        BinaryData::make_encrypted_blob(kind as u8, &plaintext, shared_key)
+    }
+
+    pub fn into_ws_message(
+        self,
+        shared_key: &SharedGatewayKey,
+    ) -> Result<Message, GatewayRequestsError> {
+        // all variants are currently encrypted
+        let blob = match self {
+            BinaryResponse::PushedMixMessage { .. } => {
+                self.into_encrypted_tagged_bytes(shared_key)?
+            }
+        };
+
+        Ok(Message::Binary(blob))
+    }
+}
@@ -0,0 +1,98 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::SharedKeyUsageError;
+use nym_credentials_interface::CompactEcashError;
+use nym_sphinx::addressing::nodes::NymNodeRoutingAddressError;
+use nym_sphinx::forwarding::packet::MixPacketFormattingError;
+use nym_sphinx::params::packet_sizes::PacketSize;
+use serde::{Deserialize, Serialize};
+use std::string::FromUtf8Error;
+use thiserror::Error;
+
+// specific errors (that should not be nested!!) for clients to match on
+#[derive(Debug, Copy, Clone, Error, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SimpleGatewayRequestsError {
+    #[error("insufficient bandwidth available to process the request. required: {required}B, available: {available}B")]
+    OutOfBandwidth { required: i64, available: i64 },
+
+    #[error("the provided ticket has already been spent before at this gateway")]
+    TicketReplay,
+}
+
+impl SimpleGatewayRequestsError {
+    pub fn is_ticket_replay(&self) -> bool {
+        matches!(self, SimpleGatewayRequestsError::TicketReplay)
+    }
+}
+
+#[derive(Debug, Error)]
+pub enum GatewayRequestsError {
+    #[error(transparent)]
+    KeyUsageFailure(#[from] SharedKeyUsageError),
+
+    #[error("the received request is malformed: {source}")]
+    MalformedRequest { source: serde_json::Error },
+
+    #[error("the received response is malformed: {source}")]
+    MalformedResponse { source: serde_json::Error },
+
+    #[error("received request with an unknown kind: {kind}")]
+    UnknownRequestKind { kind: u8 },
+
+    #[error("received response with an unknown kind: {kind}")]
+    UnknownResponseKind { kind: u8 },
+
+    #[error("the encryption flag had an unexpected value")]
+    InvalidEncryptionFlag,
+
+    #[error("the request is too short")]
+    TooShortRequest,
+
+    #[error("provided MAC is invalid")]
+    InvalidMac,
+
+    #[error("address field was incorrectly encoded: {source}")]
+    IncorrectlyEncodedAddress {
+        #[from]
+        source: NymNodeRoutingAddressError,
+    },
+
+    #[error("received request had invalid size. (actual: {0}, but expected one of: {} (ACK), {} (REGULAR), {}, {}, {} (EXTENDED))",
+        PacketSize::AckPacket.size(),
+        PacketSize::RegularPacket.size(),
+        PacketSize::ExtendedPacket8.size(),
+        PacketSize::ExtendedPacket16.size(),
+        PacketSize::ExtendedPacket32.size())
+    ]
+    RequestOfInvalidSize(usize),
+
+    #[error("received sphinx packet was malformed")]
+    MalformedSphinxPacket,
+
+    #[error("failed to serialise created sphinx packet: {0}")]
+    SphinxSerialisationFailure(#[from] MixPacketFormattingError),
+
+    #[error("the received encrypted data was malformed")]
+    MalformedEncryption,
+
+    #[error("provided packet mode is invalid")]
+    InvalidPacketMode,
+
+    #[error("failed to deserialize provided credential: {0}")]
+    EcashCredentialDeserializationFailure(#[from] CompactEcashError),
+
+    #[error("failed to deserialize provided credential: EOF")]
+    CredentialDeserializationFailureEOF,
+
+    #[error("failed to deserialize provided credential: malformed string: {0}")]
+    CredentialDeserializationFailureMalformedString(#[from] FromUtf8Error),
+
+    #[error("the provided [v1] credential has invalid number of parameters - {0}")]
+    InvalidNumberOfEmbededParameters(u32),
+
+    // variant to catch legacy errors
+    #[error("{0}")]
+    Other(String),
+}
@@ -0,0 +1,133 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{
+    BinaryRequest, BinaryRequestKind, BinaryResponse, BinaryResponseKind, GatewayRequestsError,
+    SharedGatewayKey,
+};
+use std::iter::once;
+
+// each binary message consists of the following structure (for non-legacy messages)
+// KIND || ENC_FLAG || MAYBE_NONCE || CIPHERTEXT/PLAINTEXT
+// first byte is the kind of data to influence further serialisation/deseralisation
+// second byte is a flag indicating whether the content is encrypted
+// then it's followed by a pseudorandom nonce, assuming encryption is used
+// finally, the rest of the message is the associated ciphertext or just plaintext (if message wasn't encrypted)
+pub struct BinaryData<'a> {
+    kind: u8,
+    encrypted: bool,
+    maybe_nonce: Option<&'a [u8]>,
+    data: &'a [u8],
+}
+
+impl<'a> BinaryData<'a> {
+    // serialises possibly encrypted data into bytes to be put on the wire
+    pub fn into_raw(self, legacy: bool) -> Vec<u8> {
+        if legacy {
+            return self.data.to_vec();
+        }
+
+        let i = once(self.kind).chain(once(if self.encrypted { 1 } else { 0 }));
+        if let Some(nonce) = self.maybe_nonce {
+            i.chain(nonce.iter().copied())
+                .chain(self.data.iter().copied())
+                .collect()
+        } else {
+            i.chain(self.data.iter().copied()).collect()
+        }
+    }
+
+    // attempts to perform basic parsing on bytes received from the wire
+    pub fn from_raw(
+        raw: &'a [u8],
+        available_key: &SharedGatewayKey,
+    ) -> Result<Self, GatewayRequestsError> {
+        // if we're using legacy key, it's quite simple:
+        // it's always encrypted with no nonce and the request/response kind is always 1
+        if available_key.is_legacy() {
+            return Ok(BinaryData {
+                kind: 1,
+                encrypted: true,
+                maybe_nonce: None,
+                data: raw,
+            });
+        }
+
+        if raw.len() < 2 {
+            return Err(GatewayRequestsError::TooShortRequest);
+        }
+
+        let kind = raw[0];
+        let encrypted = if raw[1] == 1 {
+            true
+        } else if raw[1] == 0 {
+            false
+        } else {
+            return Err(GatewayRequestsError::InvalidEncryptionFlag);
+        };
+
+        // if data is encrypted, there MUST be a nonce present for non-legacy keys
+        if encrypted && raw.len() < available_key.nonce_size() + 2 {
+            return Err(GatewayRequestsError::TooShortRequest);
+        }
+
+        Ok(BinaryData {
+            kind,
+            encrypted,
+            maybe_nonce: Some(&raw[2..2 + available_key.nonce_size()]),
+            data: &raw[2 + available_key.nonce_size()..],
+        })
+    }
+
+    // attempt to encrypt plaintext of provided response/request and serialise it into wire format
+    pub fn make_encrypted_blob(
+        kind: u8,
+        plaintext: &[u8],
+        key: &SharedGatewayKey,
+    ) -> Result<Vec<u8>, GatewayRequestsError> {
+        let maybe_nonce = key.random_nonce_or_zero_iv();
+
+        let ciphertext = key.encrypt(plaintext, maybe_nonce.as_deref())?;
+        Ok(BinaryData {
+            kind,
+            encrypted: true,
+            maybe_nonce: maybe_nonce.as_deref(),
+            data: &ciphertext,
+        }
+        .into_raw(key.is_legacy()))
+    }
+
+    // attempts to parse previously recovered bytes into a [`BinaryRequest`]
+    pub fn into_request(
+        self,
+        key: &SharedGatewayKey,
+    ) -> Result<BinaryRequest, GatewayRequestsError> {
+        let kind = BinaryRequestKind::from_repr(self.kind)
+            .ok_or(GatewayRequestsError::UnknownRequestKind { kind: self.kind })?;
+
+        let plaintext = if self.encrypted {
+            &*key.decrypt(self.data, self.maybe_nonce)?
+        } else {
+            self.data
+        };
+
+        BinaryRequest::from_plaintext(kind, plaintext)
+    }
+
+    // attempts to parse previously recovered bytes into a [`BinaryResponse`]
+    pub fn into_response(
+        self,
+        key: &SharedGatewayKey,
+    ) -> Result<BinaryResponse, GatewayRequestsError> {
+        let kind = BinaryResponseKind::from_repr(self.kind)
+            .ok_or(GatewayRequestsError::UnknownResponseKind { kind: self.kind })?;
+
+        let plaintext = if self.encrypted {
+            &*key.decrypt(self.data, self.maybe_nonce)?
+        } else {
+            self.data
+        };
+
+        BinaryResponse::from_plaintext(kind, plaintext)
+    }
+}
@@ -0,0 +1,18 @@
+// Copyright 2020-2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+pub mod binary_request;
+pub mod binary_response;
+pub mod error;
+mod helpers;
+pub mod registration_handshake_wrapper;
+pub mod text_request;
+pub mod text_response;
+
+// just to preserve existing imports
+pub use binary_request::*;
+pub use binary_response::*;
+pub use error::*;
+pub use registration_handshake_wrapper::*;
+pub use text_request::*;
+pub use text_response::*;
@@ -0,0 +1,103 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+
+#[derive(Serialize, Deserialize, Debug)]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum RegistrationHandshake {
+    HandshakePayload {
+        #[serde(default)]
+        protocol_version: Option<u8>,
+        data: Vec<u8>,
+    },
+    HandshakeError {
+        message: String,
+    },
+}
+
+impl RegistrationHandshake {
+    pub fn new_payload(data: Vec<u8>, protocol_version: u8) -> Self {
+        RegistrationHandshake::HandshakePayload {
+            protocol_version: Some(protocol_version),
+            data,
+        }
+    }
+
+    pub fn new_error<S: Into<String>>(message: S) -> Self {
+        RegistrationHandshake::HandshakeError {
+            message: message.into(),
+        }
+    }
+}
+
+impl FromStr for RegistrationHandshake {
+    type Err = serde_json::Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        serde_json::from_str(s)
+    }
+}
+
+impl TryFrom<String> for RegistrationHandshake {
+    type Error = serde_json::Error;
+
+    fn try_from(msg: String) -> Result<Self, serde_json::Error> {
+        msg.parse()
+    }
+}
+
+impl TryInto<String> for RegistrationHandshake {
+    type Error = serde_json::Error;
+
+    fn try_into(self) -> Result<String, serde_json::Error> {
+        serde_json::to_string(&self)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::ClientControlRequest;
+
+    #[test]
+    fn handshake_payload_can_be_deserialized_into_register_handshake_init_request() {
+        let handshake_data = vec![1, 2, 3, 4, 5, 6];
+        let handshake_payload_with_protocol = RegistrationHandshake::HandshakePayload {
+            protocol_version: Some(42),
+            data: handshake_data.clone(),
+        };
+        let serialized = serde_json::to_string(&handshake_payload_with_protocol).unwrap();
+        let deserialized = ClientControlRequest::try_from(serialized).unwrap();
+
+        match deserialized {
+            ClientControlRequest::RegisterHandshakeInitRequest {
+                protocol_version,
+                data,
+            } => {
+                assert_eq!(protocol_version, Some(42));
+                assert_eq!(data, handshake_data)
+            }
+            _ => unreachable!("this branch shouldn't have been reached!"),
+        }
+
+        let handshake_payload_without_protocol = RegistrationHandshake::HandshakePayload {
+            protocol_version: None,
+            data: handshake_data.clone(),
+        };
+        let serialized = serde_json::to_string(&handshake_payload_without_protocol).unwrap();
+        let deserialized = ClientControlRequest::try_from(serialized).unwrap();
+
+        match deserialized {
+            ClientControlRequest::RegisterHandshakeInitRequest {
+                protocol_version,
+                data,
+            } => {
+                assert!(protocol_version.is_none());
+                assert_eq!(data, handshake_data)
+            }
+            _ => unreachable!("this branch shouldn't have been reached!"),
+        }
+    }
+}
@@ -0,0 +1,199 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::models::CredentialSpendingRequest;
+use crate::{
+    GatewayRequestsError, SharedGatewayKey, SymmetricKey, AES_GCM_SIV_PROTOCOL_VERSION,
+    CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION, INITIAL_PROTOCOL_VERSION,
+};
+use nym_credentials_interface::CredentialSpendingData;
+use nym_sphinx::DestinationAddressBytes;
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+use tungstenite::Message;
+
+// wrapper for all encrypted requests for ease of use
+#[derive(Serialize, Deserialize, Debug)]
+#[non_exhaustive]
+pub enum ClientRequest {
+    UpgradeKey {
+        hkdf_salt: Vec<u8>,
+        derived_key_digest: Vec<u8>,
+    },
+}
+
+impl ClientRequest {
+    pub fn encrypt<S: SymmetricKey>(
+        &self,
+        key: &S,
+    ) -> Result<ClientControlRequest, GatewayRequestsError> {
+        // we're using json representation for few reasons:
+        // - ease of re-implementation in other languages (compared to for example bincode)
+        // - we expect all requests to be relatively small - for anything bigger use BinaryRequest!
+        // - the schema is self-describing which simplifies deserialisation
+
+        // SAFETY: the trait has been derived correctly with no weird variants
+        let plaintext = serde_json::to_vec(self).unwrap();
+        let nonce = key.random_nonce_or_iv();
+        let ciphertext = key.encrypt(&plaintext, Some(&nonce))?;
+        Ok(ClientControlRequest::EncryptedRequest { ciphertext, nonce })
+    }
+
+    pub fn decrypt<S: SymmetricKey>(
+        ciphertext: &[u8],
+        nonce: &[u8],
+        key: &S,
+    ) -> Result<Self, GatewayRequestsError> {
+        let plaintext = key.decrypt(ciphertext, Some(nonce))?;
+        serde_json::from_slice(&plaintext)
+            .map_err(|source| GatewayRequestsError::MalformedRequest { source })
+    }
+}
+
+// if you're adding new variants here, consider putting them inside `ClientRequest` instead
+#[derive(Serialize, Deserialize, Debug)]
+#[serde(tag = "type", rename_all = "camelCase")]
+#[non_exhaustive]
+pub enum ClientControlRequest {
+    // TODO: should this also contain a MAC considering that at this point we already
+    // have the shared key derived?
+    Authenticate {
+        #[serde(default)]
+        protocol_version: Option<u8>,
+        address: String,
+        enc_address: String,
+        iv: String,
+    },
+    #[serde(alias = "handshakePayload")]
+    RegisterHandshakeInitRequest {
+        #[serde(default)]
+        protocol_version: Option<u8>,
+        data: Vec<u8>,
+    },
+    BandwidthCredential {
+        enc_credential: Vec<u8>,
+        iv: Vec<u8>,
+    },
+    BandwidthCredentialV2 {
+        enc_credential: Vec<u8>,
+        iv: Vec<u8>,
+    },
+    EcashCredential {
+        enc_credential: Vec<u8>,
+        iv: Vec<u8>,
+    },
+    ClaimFreeTestnetBandwidth,
+    EncryptedRequest {
+        ciphertext: Vec<u8>,
+        nonce: Vec<u8>,
+    },
+    SupportedProtocol {},
+    // if you're adding new variants here, consider putting them inside `ClientRequest` instead
+}
+
+impl ClientControlRequest {
+    pub fn new_authenticate(
+        address: DestinationAddressBytes,
+        shared_key: &SharedGatewayKey,
+        uses_credentials: bool,
+    ) -> Result<Self, GatewayRequestsError> {
+        // if we're encrypting with non-legacy key, the remote must support AES256-GCM-SIV
+        let protocol_version = if !shared_key.is_legacy() {
+            Some(AES_GCM_SIV_PROTOCOL_VERSION)
+        } else if uses_credentials {
+            Some(CREDENTIAL_UPDATE_V2_PROTOCOL_VERSION)
+        } else {
+            // if we're not going to be using credentials, advertise lower protocol version to allow connection
+            // to wider range of gateways
+            Some(INITIAL_PROTOCOL_VERSION)
+        };
+
+        let nonce = shared_key.random_nonce_or_iv();
+        let ciphertext = shared_key.encrypt_naive(address.as_bytes_ref(), Some(&nonce))?;
+
+        Ok(ClientControlRequest::Authenticate {
+            protocol_version,
+            address: address.as_base58_string(),
+            enc_address: bs58::encode(&ciphertext).into_string(),
+            iv: bs58::encode(&nonce).into_string(),
+        })
+    }
+
+    pub fn name(&self) -> String {
+        match self {
+            ClientControlRequest::Authenticate { .. } => "Authenticate".to_string(),
+            ClientControlRequest::RegisterHandshakeInitRequest { .. } => {
+                "RegisterHandshakeInitRequest".to_string()
+            }
+            ClientControlRequest::BandwidthCredential { .. } => "BandwidthCredential".to_string(),
+            ClientControlRequest::BandwidthCredentialV2 { .. } => {
+                "BandwidthCredentialV2".to_string()
+            }
+            ClientControlRequest::EcashCredential { .. } => "EcashCredential".to_string(),
+            ClientControlRequest::ClaimFreeTestnetBandwidth => {
+                "ClaimFreeTestnetBandwidth".to_string()
+            }
+            ClientControlRequest::SupportedProtocol { .. } => "SupportedProtocol".to_string(),
+            ClientControlRequest::EncryptedRequest { .. } => "EncryptedRequest".to_string(),
+        }
+    }
+
+    pub fn new_enc_ecash_credential(
+        credential: CredentialSpendingData,
+        shared_key: &SharedGatewayKey,
+    ) -> Result<Self, GatewayRequestsError> {
+        let cred = CredentialSpendingRequest::new(credential);
+        let serialized_credential = cred.to_bytes();
+
+        let nonce = shared_key.random_nonce_or_iv();
+        let enc_credential = shared_key.encrypt(&serialized_credential, Some(&nonce))?;
+
+        Ok(ClientControlRequest::EcashCredential {
+            enc_credential,
+            iv: nonce,
+        })
+    }
+
+    pub fn try_from_enc_ecash_credential(
+        enc_credential: Vec<u8>,
+        shared_key: &SharedGatewayKey,
+        iv: Vec<u8>,
+    ) -> Result<CredentialSpendingRequest, GatewayRequestsError> {
+        let credential_bytes = shared_key.decrypt(&enc_credential, Some(&iv))?;
+        CredentialSpendingRequest::try_from_bytes(credential_bytes.as_slice())
+            .map_err(|_| GatewayRequestsError::MalformedEncryption)
+    }
+}
+
+impl From<ClientControlRequest> for Message {
+    fn from(req: ClientControlRequest) -> Self {
+        // it should be safe to call `unwrap` here as the message is generated by the server
+        // so if it fails (and consequently panics) it's a bug that should be resolved
+        let str_req = serde_json::to_string(&req).unwrap();
+        Message::Text(str_req)
+    }
+}
+
+impl TryFrom<String> for ClientControlRequest {
+    type Error = serde_json::Error;
+
+    fn try_from(msg: String) -> Result<Self, Self::Error> {
+        msg.parse()
+    }
+}
+
+impl FromStr for ClientControlRequest {
+    type Err = serde_json::Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        serde_json::from_str(s)
+    }
+}
+
+impl TryInto<String> for ClientControlRequest {
+    type Error = serde_json::Error;
+
+    fn try_into(self) -> Result<String, Self::Error> {
+        serde_json::to_string(&self)
+    }
+}
@@ -0,0 +1,130 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{GatewayRequestsError, SimpleGatewayRequestsError, SymmetricKey};
+use serde::{Deserialize, Serialize};
+use tungstenite::Message;
+
+// naming things is difficult...
+// the name implies that the content is encrypted before being sent on the wire
+#[derive(Serialize, Deserialize, Debug)]
+#[non_exhaustive]
+pub enum SensitiveServerResponse {
+    KeyUpgradeAck {},
+}
+
+impl SensitiveServerResponse {
+    pub fn encrypt<S: SymmetricKey>(
+        &self,
+        key: &S,
+    ) -> Result<ServerResponse, GatewayRequestsError> {
+        // we're using json representation for few reasons:
+        // - ease of re-implementation in other languages (compared to for example bincode)
+        // - we expect all requests to be relatively small - for anything bigger use BinaryRequest!
+        // - the schema is self-describing which simplifies deserialisation
+
+        // SAFETY: the trait has been derived correctly with no weird variants
+        let plaintext = serde_json::to_vec(self).unwrap();
+        let nonce = key.random_nonce_or_iv();
+        let ciphertext = key.encrypt(&plaintext, Some(&nonce))?;
+        Ok(ServerResponse::EncryptedResponse { ciphertext, nonce })
+    }
+
+    pub fn decrypt<S: SymmetricKey>(
+        ciphertext: &[u8],
+        nonce: &[u8],
+        key: &S,
+    ) -> Result<Self, GatewayRequestsError> {
+        let plaintext = key.decrypt(ciphertext, Some(nonce))?;
+        serde_json::from_slice(&plaintext)
+            .map_err(|source| GatewayRequestsError::MalformedRequest { source })
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+#[serde(tag = "type", rename_all = "camelCase")]
+#[non_exhaustive]
+pub enum ServerResponse {
+    Authenticate {
+        #[serde(default)]
+        protocol_version: Option<u8>,
+        status: bool,
+        bandwidth_remaining: i64,
+    },
+    Register {
+        #[serde(default)]
+        protocol_version: Option<u8>,
+        status: bool,
+    },
+    EncryptedResponse {
+        ciphertext: Vec<u8>,
+        nonce: Vec<u8>,
+    },
+    Bandwidth {
+        available_total: i64,
+    },
+    Send {
+        remaining_bandwidth: i64,
+    },
+    SupportedProtocol {
+        version: u8,
+    },
+    // Generic error
+    Error {
+        message: String,
+    },
+    // Specific typed errors
+    // so that clients could match on this variant without doing naive string matching
+    TypedError {
+        error: SimpleGatewayRequestsError,
+    },
+}
+
+impl ServerResponse {
+    pub fn name(&self) -> String {
+        match self {
+            ServerResponse::Authenticate { .. } => "Authenticate".to_string(),
+            ServerResponse::Register { .. } => "Register".to_string(),
+            ServerResponse::Bandwidth { .. } => "Bandwidth".to_string(),
+            ServerResponse::Send { .. } => "Send".to_string(),
+            ServerResponse::Error { .. } => "Error".to_string(),
+            ServerResponse::TypedError { .. } => "TypedError".to_string(),
+            ServerResponse::SupportedProtocol { .. } => "SupportedProtocol".to_string(),
+            ServerResponse::EncryptedResponse { .. } => "EncryptedResponse".to_string(),
+        }
+    }
+    pub fn new_error<S: Into<String>>(msg: S) -> Self {
+        ServerResponse::Error {
+            message: msg.into(),
+        }
+    }
+
+    pub fn is_error(&self) -> bool {
+        matches!(self, ServerResponse::Error { .. })
+    }
+
+    pub fn implies_successful_authentication(&self) -> bool {
+        match self {
+            ServerResponse::Authenticate { status, .. } => *status,
+            ServerResponse::Register { status, .. } => *status,
+            _ => false,
+        }
+    }
+}
+
+impl From<ServerResponse> for Message {
+    fn from(res: ServerResponse) -> Self {
+        // it should be safe to call `unwrap` here as the message is generated by the server
+        // so if it fails (and consequently panics) it's a bug that should be resolved
+        let str_res = serde_json::to_string(&res).unwrap();
+        Message::Text(str_res)
+    }
+}
+
+impl TryFrom<String> for ServerResponse {
+    type Error = serde_json::Error;
+
+    fn try_from(msg: String) -> Result<Self, serde_json::Error> {
+        serde_json::from_str(&msg)
+    }
+}
@@ -19,6 +19,7 @@ sqlx = { workspace = true, features = [
    "macros",
    "migrate",
    "time",
+    "chrono"
 ] }
 time = { workspace = true }
 thiserror = { workspace = true }
@@ -73,6 +73,9 @@ CREATE TABLE ticket_verification_tmp (
   PRIMARY KEY (ticket_id, signer_id)
 );

+INSERT INTO ticket_verification_tmp
+SELECT * FROM ticket_verification;
+
 DROP INDEX ticket_verification_index;
 CREATE INDEX ticket_verification_index ON ticket_verification_tmp (ticket_id);

@@ -85,6 +88,9 @@ CREATE TABLE verified_tickets_tmp (
   proposal_id         INTEGER REFERENCES redemption_proposals(proposal_id)
 );

+INSERT INTO verified_tickets_tmp
+SELECT * FROM verified_tickets;
+
 DROP INDEX verified_tickets_index;
 CREATE INDEX verified_tickets_index ON verified_tickets_tmp (proposal_id);

@@ -0,0 +1,13 @@
+/*
+ * Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+ * SPDX-License-Identifier: GPL-3.0-only
+ */
+
+-- make aes128 key column nullable and add aes256 column
+ALTER TABLE shared_keys RENAME COLUMN derived_aes128_ctr_blake3_hmac_keys_bs58 TO derived_aes128_ctr_blake3_hmac_keys_bs58_old;
+ALTER TABLE shared_keys ADD COLUMN derived_aes128_ctr_blake3_hmac_keys_bs58 TEXT;
+ALTER TABLE shared_keys ADD COLUMN derived_aes256_gcm_siv_key BLOB;
+
+UPDATE shared_keys SET derived_aes128_ctr_blake3_hmac_keys_bs58 = derived_aes128_ctr_blake3_hmac_keys_bs58_old;
+
+ALTER TABLE shared_keys DROP COLUMN derived_aes128_ctr_blake3_hmac_keys_bs58_old;
@@ -0,0 +1,10 @@
+/*
+ * Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+ALTER TABLE wireguard_peer
+ADD COLUMN client_id INTEGER REFERENCES clients(id) DEFAULT NULL;
+
+ALTER TABLE wireguard_peer
+DROP COLUMN suspended;
@@ -7,6 +7,7 @@ use crate::models::Client;

 #[derive(Debug, PartialEq, sqlx::Type)]
 #[sqlx(type_name = "TEXT")] // SQLite TEXT type
+#[sqlx(rename_all = "snake_case")]
 pub enum ClientType {
    EntryMixnet,
    ExitMixnet,
@@ -11,6 +11,9 @@ pub enum StorageError {
    #[error("Failed to perform database migration: {0}")]
    MigrationError(#[from] sqlx::migrate::MigrateError),

+    #[error("could not find any valid shared keys for under id {id}")]
+    MissingSharedKey { id: i64 },
+
    #[error("Somehow stored data is incorrect: {0}")]
    DataCorruption(String),

@@ -11,7 +11,7 @@ use models::{
    VerifiedTicket, WireguardPeer,
 };
 use nym_credentials_interface::ClientTicket;
-use nym_gateway_requests::registration::handshake::SharedKeys;
+use nym_gateway_requests::shared_key::SharedGatewayKey;
 use nym_sphinx::DestinationAddressBytes;
 use shared_keys::SharedKeysManager;
 use sqlx::ConnectOptions;
@@ -42,11 +42,13 @@ pub trait Storage: Send + Sync {
    /// # Arguments
    ///
    /// * `client_address`: base58-encoded address of the client
-    /// * `shared_keys`: shared encryption (AES128CTR) and mac (hmac-blake3) derived shared keys to store.
+    /// * `shared_keys`:
+    ///     - legacy: shared encryption (AES128CTR) and mac (hmac-blake3) derived shared keys to store.
+    ///     - current: shared AES256-GCM-SIV keys
    async fn insert_shared_keys(
        &self,
        client_address: DestinationAddressBytes,
-        shared_keys: &SharedKeys,
+        shared_keys: &SharedGatewayKey,
    ) -> Result<i64, StorageError>;

    /// Tries to retrieve shared keys stored for the particular client.
@@ -225,12 +227,14 @@ pub trait Storage: Send + Sync {
    /// # Arguments
    ///
    /// * `peer`: wireguard peer data to be stored
-    /// * `suspended`: if peer exists, but it's currently suspended
+    /// * `with_client_id`: if the peer should have a corresponding client_id
+    ///   (created with entry wireguard ticket) or live without one (or with an
+    ///   exiting one), for temporary backwards compatibility.
    async fn insert_wireguard_peer(
        &self,
        peer: &defguard_wireguard_rs::host::Peer,
-        suspended: bool,
-    ) -> Result<(), StorageError>;
+        with_client_id: bool,
+    ) -> Result<Option<i64>, StorageError>;

    /// Tries to retrieve available bandwidth for the particular peer.
    ///
@@ -330,17 +334,27 @@ impl Storage for PersistentStorage {
    async fn insert_shared_keys(
        &self,
        client_address: DestinationAddressBytes,
-        shared_keys: &SharedKeys,
+        shared_keys: &SharedGatewayKey,
    ) -> Result<i64, StorageError> {
-        let client_id = self
-            .client_manager
-            .insert_client(ClientType::EntryMixnet)
-            .await?;
+        let client_address_bs58 = client_address.as_base58_string();
+        let client_id = match self
+            .shared_key_manager
+            .client_id(&client_address_bs58)
+            .await
+        {
+            Ok(client_id) => client_id,
+            _ => {
+                self.client_manager
+                    .insert_client(ClientType::EntryMixnet)
+                    .await?
+            }
+        };
        self.shared_key_manager
            .insert_shared_keys(
                client_id,
-                client_address.as_base58_string(),
-                shared_keys.to_base58_string(),
+                client_address_bs58,
+                shared_keys.aes128_ctr_hmac_bs58().as_deref(),
+                shared_keys.aes256_gcm_siv().as_deref(),
            )
            .await?;
        Ok(client_id)
@@ -637,12 +651,30 @@ impl Storage for PersistentStorage {
    async fn insert_wireguard_peer(
        &self,
        peer: &defguard_wireguard_rs::host::Peer,
-        suspended: bool,
-    ) -> Result<(), StorageError> {
+        with_client_id: bool,
+    ) -> Result<Option<i64>, StorageError> {
+        let client_id = match self
+            .wireguard_peer_manager
+            .retrieve_peer(&peer.public_key.to_string())
+            .await?
+        {
+            Some(peer) => peer.client_id,
+            _ => {
+                if with_client_id {
+                    Some(
+                        self.client_manager
+                            .insert_client(ClientType::EntryWireguard)
+                            .await?,
+                    )
+                } else {
+                    None
+                }
+            }
+        };
        let mut peer = WireguardPeer::from(peer.clone());
-        peer.suspended = suspended;
+        peer.client_id = client_id;
        self.wireguard_peer_manager.insert_peer(&peer).await?;
-        Ok(())
+        Ok(client_id)
    }

    async fn get_wireguard_peer(
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Jędrzej Stuczyński	69a34418ab	ignore precommits from missing validators	2025-06-23 10:46:01 +01:00
Jędrzej Stuczyński	fd00405245	allow conversion from CometBFT block subscription	2025-02-19 14:56:40 +00:00
Jędrzej Stuczyński	7d77a9231c	old validator rewarder with updated cosmrs	2025-02-19 14:33:37 +00:00
Jędrzej Stuczyński	e37145422c	Merge pull request #4942 from nymtech/bugfix/rewarder-post-pruning-adjustments Bugfix/rewarder post pruning adjustments	2024-09-27 18:23:32 +01:00
Jędrzej Stuczyński	4ad52accc0	fixed stabilised clippy issue	2024-09-27 18:10:59 +01:00
Jędrzej Stuczyński	784fae2204	fix logic for determining end height for processing block ranges	2024-09-27 17:53:55 +01:00
Jędrzej Stuczyński	8aa5711bee	fixed query for historical validator data	2024-09-27 17:48:56 +01:00
Jędrzej Stuczyński	07022314fc	fixed typos and formatting	2024-09-27 16:51:45 +01:00
Jędrzej Stuczyński	76c3081470	introduced rewarding resync alongside recovery instructions	2024-09-27 16:41:07 +01:00
Jędrzej Stuczyński	d399161d31	adjust 'process_until' command to allow empty stop height	2024-09-27 16:35:53 +01:00
Jędrzej Stuczyński	27fb4ae0cc	log error when rewarding fails due to missing blocks	2024-09-27 16:21:27 +01:00
Jędrzej Stuczyński	74392a2886	don't request useless blocks during startup sync	2024-09-27 15:53:16 +01:00
Jędrzej Stuczyński	457c478a03	introduced cli command to process a block range	2024-09-27 15:15:13 +01:00
Jędrzej Stuczyński	5e95992427	introduced cli command to process an individual block	2024-09-27 14:57:39 +01:00
Jędrzej Stuczyński	d7eecd481c	decreased SOCKET_FAILURE_RESET the previous value of 2h was way too big. especially since it was quite likely for multiple failures to occur hourly during increased validator load when mixnet epoch was getting transitioned	2024-09-27 14:13:09 +01:00
import this	e08fc4894b	[DOCs/operators]: Release notes v2024.11-wedel (#4939 ) * finish release notes * add a note	2024-09-27 13:12:15 +00:00
Bogdan-Ștefan Neacşu	fabd48b7ea	Fix broken build after merge (#4937 )	2024-09-26 18:44:21 +02:00
Bogdan-Ștefan Neacşu	894e0bd1bf	Add more conversions for responses of authenticator messages (#4929 ) * More conversions for responses * Expose version	2024-09-26 18:00:13 +02:00
benedetta davico	f76300669a	Merge pull request #4931 from nymtech/feature/wedel-merge-conflicts Wedel release to develop	2024-09-26 13:46:24 +02:00
Jędrzej Stuczyński	333ace1f97	Merge branch 'release/2024.11-wedel' into feature/wedel-merge-conflicts	2024-09-26 08:56:11 +01:00
Dinko Zdravac	487bf6732e	Assume offline mode in sqlx (#4926 ) * Assume offline mode * PR feedback	2024-09-25 13:28:36 +02:00
Jędrzej Stuczyński	5d4a0fef55	Merge pull request #4871 from nymtech/chore/remove-another-mixnet-migration chore: remove queued migration for adding explicit admin	2024-09-25 09:37:49 +01:00
Jon Häggblad	1627146c0e	Make ip-packet-request VERSION pub (#4925 )	2024-09-25 09:56:32 +02:00
Dinko Zdravac	ae40a00b8f	Data Observatory stub (#4905 ) * Data Observatory stub * Fix sqlx in CI * Add troubleshooting tips for sqlx * Update CI paths to trigger for this package * Add this to CI upload binary build	2024-09-24 16:48:15 +02:00
Jon Häggblad	7f3c0470e0	Fix argument to cargo-deny action (#4922 )	2024-09-24 13:17:35 +02:00
Bogdan-Ștefan Neacşu	1bc26ed79f	Expose error type (#4924 )	2024-09-24 11:48:54 +02:00
mx	60fa5cfeb8	Max/rust sdk stream abstraction (#4743 ) * add TcpProxyClient and TcpProxyServer abstractions to SDK * add single connection example * add multi-connection example * add simple echo server to `tools/`: used for multi-connection example * update FFI toml files: switched to local imports * add proxy bindings to `ffi/shared` * add proxy bindings and example to `ffi/go` * add note to `ffi/cpp` about lack of Proxy bindings for the moment	2024-09-24 09:29:46 +00:00
Jon Häggblad	3b7088aeea	Fix nymvpn.com url in mainnet defaults (#4920 )	2024-09-24 10:25:27 +02:00
Bogdan-Ștefan Neacşu	179d214e21	Check both version and type in message header (#4918 ) * Move client type to the client code * Check both version and type in header	2024-09-23 17:57:03 +02:00
Jon Häggblad	2a94ce6443	Bump http-api-client default timeout to 30 sec (#4917 )	2024-09-23 15:45:47 +02:00
Bogdan-Ștefan Neacşu	95ec91daa1	Entry wireguard tickets (#4888 ) * Create credential verifier in authenticator * Add new version of peer storage with client id * Fix v1 to what it was before * Compact storage into ecash verifier * Fix non-linux build * Less overlapping conditions * Remove moved code * Use handler thread for each peer * Re-spawn stored handles at startup * Keep new function without async & Result * Put query peer in function too * Query bandwidth * Fix clippy * Replace tap with inspect_err * Fix copyright year * Handle version 2 on the reqeust deser * Add protocol type in req/resp messages	2024-09-23 14:49:18 +02:00
benedettadavico	803850be74	bump versions & update changelog	2024-09-23 10:00:20 +02:00
Drazen Urch	2f267cf787	Update network monitor entrypoint (#4893 ) * Update entrypoint * Update CI action * Rollback ci changes	2024-09-20 10:58:50 +02:00
Jędrzej Stuczyński	0d2418ef6a	Merge pull request #4885 from nymtech/feature/updated-gateway-registration Feature/updated gateway registration	2024-09-20 09:09:28 +01:00
Bogdan-Ștefan Neacşu	6f0c8dbe73	Fix missing duplication of modified tables (#4904 )	2024-09-19 18:25:21 +02:00
mx	2198c1bd7b	added new instructions for building locally (#4902 )	2024-09-19 15:48:51 +00:00
Jędrzej Stuczyński	be7f00fe52	replaced an assertion with an error return instead	2024-09-19 15:59:04 +01:00
Jon Häggblad	35c94f5c4b	Update cargo deny (#4901 ) * Regenerate deny.toml * Backport old settings to deny.toml * Explicitly allow GPL-3 only on our own specific crates * Update deny.toml for latest changes * Fix cargo-deny warnings for duplicate crates * Update cargo-deny-action to v2	2024-09-19 12:53:27 +02:00
Jędrzej Stuczyński	f5863b9668	fixed client key upgrade due to extra Arc	2024-09-19 11:06:50 +01:00
dependabot[bot]	963c54fea2	build(deps): bump semver from 0.11.0 to 1.0.23 (#4881 ) * build(deps): bump semver from 0.11.0 to 1.0.23 Bumps [semver](https://github.com/dtolnay/semver) from 0.11.0 to 1.0.23. - [Release notes](https://github.com/dtolnay/semver/releases) - [Commits](https://github.com/dtolnay/semver/compare/0.11.0...1.0.23) --- updated-dependencies: - dependency-name: semver dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> * Update for 1.0 --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Jon Häggblad <jon.haggblad@gmail.com>	2024-09-19 11:55:10 +02:00
dependabot[bot]	db55a96f91	build(deps): bump toml from 0.5.11 to 0.8.14 (#4805 ) * build(deps): bump toml from 0.5.11 to 0.8.14 Bumps [toml](https://github.com/toml-rs/toml) from 0.5.11 to 0.8.14. - [Commits](https://github.com/toml-rs/toml/compare/toml-v0.5.11...toml-v0.8.14) --- updated-dependencies: - dependency-name: toml dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> * Use workspace dependency --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Jon Häggblad <jon.haggblad@gmail.com>	2024-09-19 11:10:34 +02:00
Jędrzej Stuczyński	7c0235ab26	fixed wasm build and trait impl	2024-09-19 10:06:59 +01:00
dependabot[bot]	92af6f7024	build(deps): bump hyper from 1.3.1 to 1.4.1 (#4879 ) Bumps [hyper](https://github.com/hyperium/hyper) from 1.3.1 to 1.4.1. - [Release notes](https://github.com/hyperium/hyper/releases) - [Changelog](https://github.com/hyperium/hyper/blob/master/CHANGELOG.md) - [Commits](https://github.com/hyperium/hyper/compare/v1.3.1...v1.4.1) --- updated-dependencies: - dependency-name: hyper dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-09-19 11:06:49 +02:00
Sachin Kamath	7146c4c012	docs: add hostname instructions for wss (#4900 )	2024-09-19 08:55:28 +00:00
Jędrzej Stuczyński	3dc62a9a60	Merge pull request #4892 from nymtech/bugfix/ticketbook-false-double-spending Bugfix/ticketbook false double spending	2024-09-19 09:44:43 +01:00
Jędrzej Stuczyński	b3d7c26443	added key upgrade mechanism	2024-09-18 17:43:47 +01:00
Jędrzej Stuczyński	9efeef881a	split types.rs + added additional helpers	2024-09-18 17:43:44 +01:00
Jędrzej Stuczyński	9d8369a5b2	generate pseudorandom salt for deriving aes256gcm-siv key	2024-09-18 17:43:43 +01:00
Jędrzej Stuczyński	cc32eb3904	fixed wasm build	2024-09-18 17:43:43 +01:00
Jędrzej Stuczyński	8cf4977021	assert new gateway keys zeroize on drop	2024-09-18 17:43:43 +01:00
Jędrzej Stuczyński	2c2748832c	cargo fmt	2024-09-18 17:43:42 +01:00
Jędrzej Stuczyński	114db3c1cf	post-rebasing fixes	2024-09-18 17:43:42 +01:00
Jędrzej Stuczyński	a65df5a0ab	clippy	2024-09-18 17:43:42 +01:00
Jędrzej Stuczyński	b6f07fbfce	warning for unimplemented upgrade	2024-09-18 17:43:42 +01:00
Jędrzej Stuczyński	c39d42b7dd	fixed deserialisation of updated gateway shared materials	2024-09-18 17:43:41 +01:00
Jędrzej Stuczyński	21e9df488f	compatibility with legacy clients	2024-09-18 17:43:40 +01:00
Jędrzej Stuczyński	94113206b2	completing handshake using legacy keys	2024-09-18 17:43:07 +01:00
Jędrzej Stuczyński	71532484a9	updated client handshake to allow derivation of different key types	2024-09-18 17:43:07 +01:00
Jędrzej Stuczyński	8756763875	added support for aead in nym-crypto	2024-09-18 17:43:06 +01:00
Jędrzej Stuczyński	5753b79997	slightly refactored bandwidth tracking	2024-09-18 11:27:35 +01:00
Jędrzej Stuczyński	2a6aa13ecd	fixed client bandwidth being not correctly deducted	2024-09-18 11:12:24 +01:00
Jon Häggblad	9213e02b43	Remove clippy annotation (#4896 )	2024-09-18 11:47:41 +02:00
Jon Häggblad	ede4b23e8a	Fix clippy::too-long-first-doc-paragraph (#4897 )	2024-09-18 10:25:49 +02:00
Jon Häggblad	2e95ea16f9	Update nym-vpn metapackage and replace nymvpn-x with nym-vpn-app (#4889 ) * Update nym-vpn metapackage to 0.2.0 and replace nymvpn-x with nym-vpn-app * Fix compression * Update description	2024-09-18 09:16:17 +01:00
benedetta davico	d5c9e1d8cb	Merge pull request #4899 from nymtech/jon/cherry-pick-4894-into-wedel Backport #4894 to fix ci	2024-09-18 09:28:15 +02:00
dependabot[bot]	0c955817fd	build(deps): bump the patch-updates group across 1 directory with 9 updates (#4898 ) Bumps the patch-updates group with 9 updates in the / directory: \| Package \| From \| To \| \| --- \| --- \| --- \| \| [anyhow](https://github.com/dtolnay/anyhow) \| `1.0.87` \| `1.0.89` \| \| [clap_complete](https://github.com/clap-rs/clap) \| `4.5.5` \| `4.5.28` \| \| [clap_complete_fig](https://github.com/clap-rs/clap) \| `4.5.1` \| `4.5.2` \| \| [curve25519-dalek](https://github.com/dalek-cryptography/curve25519-dalek) \| `4.1.2` \| `4.1.3` \| \| [getset](https://github.com/jbaublitz/getset) \| `0.1.2` \| `0.1.3` \| \| [log](https://github.com/rust-lang/log) \| `0.4.21` \| `0.4.22` \| \| [quote](https://github.com/dtolnay/quote) \| `1.0.36` \| `1.0.37` \| \| [safer-ffi](https://github.com/getditto/safer_ffi) \| `0.1.12` \| `0.1.13` \| \| [url](https://github.com/servo/rust-url) \| `2.5.1` \| `2.5.2` \| Updates `anyhow` from 1.0.87 to 1.0.89 - [Release notes](https://github.com/dtolnay/anyhow/releases) - [Commits](https://github.com/dtolnay/anyhow/compare/1.0.87...1.0.89) Updates `clap_complete` from 4.5.5 to 4.5.28 - [Release notes](https://github.com/clap-rs/clap/releases) - [Changelog](https://github.com/clap-rs/clap/blob/master/CHANGELOG.md) - [Commits](https://github.com/clap-rs/clap/compare/clap_complete-v4.5.5...clap_complete-v4.5.28) Updates `clap_complete_fig` from 4.5.1 to 4.5.2 - [Release notes](https://github.com/clap-rs/clap/releases) - [Changelog](https://github.com/clap-rs/clap/blob/master/CHANGELOG.md) - [Commits](https://github.com/clap-rs/clap/compare/clap_complete_fig-v4.5.1...clap_complete_fig-v4.5.2) Updates `curve25519-dalek` from 4.1.2 to 4.1.3 - [Release notes](https://github.com/dalek-cryptography/curve25519-dalek/releases) - [Commits](https://github.com/dalek-cryptography/curve25519-dalek/compare/curve25519-4.1.2...curve25519-4.1.3) Updates `getset` from 0.1.2 to 0.1.3 - [Release notes](https://github.com/jbaublitz/getset/releases) - [Commits](https://github.com/jbaublitz/getset/compare/0.1.2...0.1.3) Updates `log` from 0.4.21 to 0.4.22 - [Release notes](https://github.com/rust-lang/log/releases) - [Changelog](https://github.com/rust-lang/log/blob/master/CHANGELOG.md) - [Commits](https://github.com/rust-lang/log/compare/0.4.21...0.4.22) Updates `quote` from 1.0.36 to 1.0.37 - [Release notes](https://github.com/dtolnay/quote/releases) - [Commits](https://github.com/dtolnay/quote/compare/1.0.36...1.0.37) Updates `safer-ffi` from 0.1.12 to 0.1.13 - [Release notes](https://github.com/getditto/safer_ffi/releases) - [Commits](https://github.com/getditto/safer_ffi/commits) Updates `url` from 2.5.1 to 2.5.2 - [Release notes](https://github.com/servo/rust-url/releases) - [Commits](https://github.com/servo/rust-url/compare/v2.5.1...v2.5.2) --- updated-dependencies: - dependency-name: anyhow dependency-type: direct:production update-type: version-update:semver-patch dependency-group: patch-updates - dependency-name: clap_complete dependency-type: direct:production update-type: version-update:semver-patch dependency-group: patch-updates - dependency-name: clap_complete_fig dependency-type: direct:production update-type: version-update:semver-patch dependency-group: patch-updates - dependency-name: curve25519-dalek dependency-type: direct:production update-type: version-update:semver-patch dependency-group: patch-updates - dependency-name: getset dependency-type: direct:production update-type: version-update:semver-patch dependency-group: patch-updates - dependency-name: log dependency-type: direct:production update-type: version-update:semver-patch dependency-group: patch-updates - dependency-name: quote dependency-type: direct:production update-type: version-update:semver-patch dependency-group: patch-updates - dependency-name: safer-ffi dependency-type: direct:production update-type: version-update:semver-patch dependency-group: patch-updates - dependency-name: url dependency-type: direct:production update-type: version-update:semver-patch dependency-group: patch-updates ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-09-18 09:15:11 +02:00
Jon Häggblad	87751894d9	Fix apt install in ci-build-upload-binaries.yml (#4894 )	2024-09-18 09:07:45 +02:00
dependabot[bot]	ec3c4fb1aa	build(deps): bump sysinfo from 0.30.12 to 0.30.13 (#4880 ) Bumps [sysinfo](https://github.com/GuillaumeGomez/sysinfo) from 0.30.12 to 0.30.13. - [Changelog](https://github.com/GuillaumeGomez/sysinfo/blob/master/CHANGELOG.md) - [Commits](https://github.com/GuillaumeGomez/sysinfo/commits/v0.30.13) --- updated-dependencies: - dependency-name: sysinfo dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-09-18 00:33:44 +02:00
dependabot[bot]	789221f144	build(deps): bump comfy-table from 6.2.0 to 7.1.1 (#4882 ) Bumps [comfy-table](https://github.com/nukesor/comfy-table) from 6.2.0 to 7.1.1. - [Release notes](https://github.com/nukesor/comfy-table/releases) - [Changelog](https://github.com/Nukesor/comfy-table/blob/main/CHANGELOG.md) - [Commits](https://github.com/nukesor/comfy-table/compare/v6.2.0...v7.1.1) --- updated-dependencies: - dependency-name: comfy-table dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-09-18 00:30:46 +02:00
Jon Häggblad	5b925d8b68	Fix apt install in ci-build-upload-binaries.yml (#4894 )	2024-09-17 23:29:36 +02:00
Jędrzej Stuczyński	c8c3928575	put client bandwidth (gateway-side) behind shared pointer	2024-09-17 18:40:24 +01:00
Jędrzej Stuczyński	2fa8da8117	making sure there can be only a single client task claiming more bandwidth	2024-09-17 18:39:49 +01:00
Jędrzej Stuczyński	4548ef4d05	adding extra logs	2024-09-17 18:39:01 +01:00
Jędrzej Stuczyński	7f147ee2b0	Merge pull request #4891 from nymtech/bugfix/ticketbook-aux-imports fix: allow updating globally stored signatures	2024-09-17 15:33:34 +01:00
Jędrzej Stuczyński	48bcd7e802	fix: allow updating globally stored signatures	2024-09-17 14:21:42 +01:00
Drazen Urch	6598d677da	Build and Push CI (#4887 )	2024-09-17 10:26:45 +02:00
import this	e736a01ecc	[DOCs/operators]: Document changelog for patch/2024.10-caramello (#4886 ) * changelog for patched release * fix typo	2024-09-17 08:26:22 +00:00
Jędrzej Stuczyński	a708fa2d4a	Merge pull request #4873 from nymtech/feature/stateless-gateway-requests allow clients to send stateless gateway requests without prior registration	2024-09-16 17:00:15 +01:00
Drazen Urch	a512217382	Few fixes (#4883 )	2024-09-16 17:15:40 +02:00
Jon Häggblad	086611c7ac	Use serde from workspace (#4833 ) * cargo autoinherit for serde * cargo autoinherit for bs58 and vergen in cosmwasm-smart-contracts	2024-09-16 11:16:21 +02:00
import this	05d6652177	[DOCs/operators]: Post release docs updates (#4874 ) * update proxy setup syntax * update known errors and bugs * docs: simplify wss --------- Co-authored-by: Sachin Kamath <github@skamath.me>	2024-09-13 13:16:34 +00:00
Bogdan-Ștefan Neacşu	9c514fe3b7	Fix snake case serde (#4875 )	2024-09-13 11:53:39 +02:00
benedettadavico	aad028be3f	update qa env	2024-09-13 11:48:49 +02:00
Jędrzej Stuczyński	924160b3e7	removed unused import	2024-09-12 17:29:34 +01:00
Jędrzej Stuczyński	23d14b60de	allow handling multiple of stateless requests on the same underlying connection	2024-09-12 16:54:56 +01:00
Jędrzej Stuczyński	a4b47ef3a5	allow clients to send stateless gateway requests without prior registration	2024-09-12 15:57:38 +01:00
Bogdan-Ștefan Neacşu	6db3b34bcb	Bump defguard to github latest version (#4872 ) * Bump defguard to github latest version * Fix comment location	2024-09-12 13:49:33 +02:00
Jędrzej Stuczyński	f9383578da	chore: remove queued migration for adding explicit admin	2024-09-12 11:03:51 +01:00