Feature Noise XKpsk3 : Fix localnet (#4465)

* add custom mixnet option for gateways

* add custom mixnet option for mixnode

* change topology construction as to not miss described_nodes

* adapt localnet scripts to new topology

* add snake_case alias to described_nodes

.github/workflows/ci-build-upload-binaries.yml

@@ -9,10 +9,17 @@ on:
         default: false
         type: boolean
       enable_wireguard:
-        description: 'Add --features wireguard'
+        description: "Add --features wireguard"
         required: true
         default: false
         type: boolean
+      enable_deb:
+        description: "True to enable cargo-deb installation and .deb package building"
+        required: false
+        default: false
+        type: boolean
+  schedule:
+    - cron: "14 0 * * *"
   pull_request:
     paths:
       - "clients/**"
@@ -28,6 +35,7 @@ on:
       - "sdk/rust/nym-sdk/**"
       - "service-providers/**"
       - "tools/**"
+      - "nymvisor/**"
 
 jobs:
   publish-nym:
@@ -62,7 +70,9 @@ jobs:
       - name: Set CARGO_FEATURES
         run: |
           echo 'CARGO_FEATURES=--features wireguard' >> $GITHUB_ENV
-        if: github.event_name == 'workflow_dispatch' && inputs.enable_wireguard == true
+        if: >
+          github.event_name == 'schedule' ||
+          (github.event_name == 'workflow_dispatch' && inputs.enable_wireguard == true)
 
       - name: Install Rust stable
         uses: actions-rs/toolchain@v1
@@ -80,12 +90,12 @@ jobs:
         with:
           command: install
           args: cargo-deb
+        if: github.event_name == 'workflow_dispatch' && inputs.enable_deb == true
 
       - name: Build deb packages
         shell: bash
         run: make deb
-
-      # If this was a manual workflow_dispatch, publish binaries.
+        if: github.event_name == 'workflow_dispatch' && inputs.enable_deb == true
 
       - name: Upload Artifact
         if: github.event_name == 'workflow_dispatch'
@@ -101,12 +111,13 @@ jobs:
             target/release/nym-network-requester
             target/release/nym-network-statistics
             target/release/nym-cli
+            target/release/nymvisor
           retention-days: 30
 
-      # If this was a pull_request, upload to build server
+      # If this was a pull_request or nightly, upload to build server
 
       - name: Prepare build output
-        if: github.event_name == 'pull_request'
+        # if: github.event_name == 'schedule' || github.event_name == 'pull_request'
         shell: bash
         env:
           OUTPUT_DIR: ci-builds/${{ github.ref_name }}
@@ -118,12 +129,14 @@ jobs:
           cp target/release/nym-api $OUTPUT_DIR
           cp target/release/nym-network-requester $OUTPUT_DIR
           cp target/release/nym-network-statistics $OUTPUT_DIR
+          cp target/release/nymvisor $OUTPUT_DIR
           cp target/release/nym-cli $OUTPUT_DIR
           cp target/release/explorer-api $OUTPUT_DIR
-          cp target/debian/*.deb $OUTPUT_DIR
+          if [ ${{ github.event_name == 'workflow_dispatch' && inputs.enable_deb == true }} = true ]; then
+            cp target/debian/*.deb $OUTPUT_DIR
+          fi
 
       - name: Deploy branch to CI www
-        if: github.event_name == 'pull_request'
         continue-on-error: true
         uses: easingthemes/ssh-deploy@main
         env:

.github/workflows/publish-nym-binaries.yml

@@ -1,4 +1,4 @@
-name: Publish Nym binaries
+name: publish-nym-binaries
 
 on:
   workflow_dispatch:
@@ -29,6 +29,7 @@ jobs:
       client_hash: ${{ steps.binary-hashes.outputs.client_hash }}
       mixnode_hash: ${{ steps.binary-hashes.outputs.mixnode_hash }}
       gateway_hash: ${{ steps.binary-hashes.outputs.gateway_hash }}
+      nymvisor_hash: ${{ steps.binary-hashes.outputs.nymvisor_hash }}
       socks5_hash: ${{ steps.binary-hashes.outputs.socks5_hash }}
       netreq_hash: ${{ steps.binary-hashes.outputs.netreq_hash }}
       cli_hash: ${{ steps.binary-hashes.outputs.cli_hash }}
@@ -36,6 +37,7 @@ jobs:
       client_version: ${{ steps.binary-versions.outputs.client_version }}
       mixnode_version: ${{ steps.binary-versions.outputs.mixnode_version }}
       gateway_version: ${{ steps.binary-versions.outputs.gateway_version }}
+      nymvisor_version: ${{ steps.binary-versions.outputs.nymvisor_version }}
       socks5_version: ${{ steps.binary-versions.outputs.socks5_version }}
       netreq_version: ${{ steps.binary-versions.outputs.netreq_version }}
       cli_version: ${{ steps.binary-versions.outputs.cli_version }}
@@ -78,6 +80,7 @@ jobs:
             target/release/nym-network-requester
             target/release/nym-network-statistics
             target/release/nym-cli
+            target/release/nymvisor
           retention-days: 30
 
       - id: create-release
@@ -95,6 +98,7 @@ jobs:
             target/release/nym-network-requester
             target/release/nym-network-statistics
             target/release/nym-cli
+            target/release/nymvisor
 
   push-release-data-client:
     if: ${{ (startsWith(github.ref, 'refs/tags/nym-binaries-') && github.event_name == 'release') || github.event_name == 'workflow_dispatch' }}

.github/workflows/publish-nym-connect-macos.yml

@@ -1,4 +1,4 @@
-name: Publish Nym Connect - desktop (MacOS)
+name: publish-nym-connect-macos
 on:
   workflow_dispatch:
   release:

.github/workflows/publish-nym-connect-ubuntu.yml

@@ -1,4 +1,4 @@
-name: Publish Nym Connect - desktop (Ubuntu)
+name: publish-nym-connect-ubuntu
 on:
   workflow_dispatch:
   release:

.github/workflows/publish-nym-connect-win10.yml

@@ -1,4 +1,4 @@
-name: Publish Nym Connect - desktop (Windows 10)
+name: publish-nym-connect-win10
 on:
   workflow_dispatch:
   release:

.github/workflows/publish-nym-contracts.yml

@@ -1,4 +1,4 @@
-name: Build release of Nym smart contracts
+name: publish-nym-contracts
 on:
   workflow_dispatch:
   release:

.github/workflows/publish-nym-wallet-macos.yml

@@ -1,4 +1,4 @@
-name: Publish Nym Wallet (MacOS)
+name: publish-nym-wallet-macos
 on:
   workflow_dispatch:
   release:

.github/workflows/publish-nym-wallet-ubuntu.yml

@@ -1,4 +1,4 @@
-name: Publish Nym Wallet (Ubuntu)
+name: publish-nym-wallet-ubuntu
 on:
   workflow_dispatch:
   release:

.github/workflows/publish-nym-wallet-win10.yml

@@ -1,4 +1,4 @@
-name: Publish Nym Wallet (Windows 10)
+name: publish-nym-wallet-win10
 on:
   workflow_dispatch:
   release:

.github/workflows/publish-sdk-npm.yml

@@ -1,4 +1,4 @@
-name: Publish Typescript SDK
+name: publish-sdk-npm
 on:
   workflow_dispatch:
 

.github/workflows/release-calculate-hash.yml

@@ -1,4 +1,4 @@
-name: Releases - calculate file hashes
+name: release-calculate-hash
 
 on:
   workflow_call:

CHANGELOG.md

@@ -4,6 +4,23 @@ Post 1.0.0 release, the changelog format is based on [Keep a Changelog](https://
 
 ## [Unreleased]
 
+## [2024.1-marabou] (2024-02-15)
+
+**New Features:**
+- Introduced nymvisor support for nym-api, gateway, and mixnode binaries ([#4158])
+- Revamped nym-api execution with the addition of init and run commands ([#4225])
+
+**Enhancements:**
+- Implemented internal improvements for gateways to optimize internal packet routing
+- Improved routing score calculation
+
+**Bug Fixes:**
+- Resolved various bugs to enhance overall stability
+
+[#4158]: https://github.com/nymtech/nym/pull/4158
+[#4225]: https://github.com/nymtech/nym/pull/4225
+
+
 ## [2023.5-rolo] (2023-11-28)
 
 - Gateway won't open websocket listener until embedded Network Requester becomes available ([#4166])

Cargo.toml

@@ -32,7 +32,7 @@ members = [
     "common/cosmwasm-smart-contracts/coconut-bandwidth-contract",
     "common/cosmwasm-smart-contracts/coconut-dkg",
     "common/cosmwasm-smart-contracts/contracts-common",
-    "common/cosmwasm-smart-contracts/ephemera",
+#    "common/cosmwasm-smart-contracts/ephemera",
     "common/cosmwasm-smart-contracts/group-contract",
     "common/cosmwasm-smart-contracts/mixnet-contract",
     "common/cosmwasm-smart-contracts/multisig-contract",
@@ -56,6 +56,7 @@ members = [
     "common/node-tester-utils",
     "common/nonexhaustive-delayqueue",
     "common/nymcoconut",
+    "common/nym-id",
     "common/nymsphinx",
     "common/nymsphinx/acknowledgements",
     "common/nymsphinx/addressing",
@@ -104,8 +105,9 @@ members = [
     "nym-outfox",
     "nym-validator-rewarder",
     "tools/internal/ssl-inject",
-    "tools/internal/sdk-version-bump",
+    # "tools/internal/sdk-version-bump",
     "tools/nym-cli",
+    "tools/nym-id-cli",
     "tools/nym-nr-query",
     "tools/nymvisor",
     "tools/ts-rs-cli",
@@ -143,6 +145,7 @@ anyhow = "1.0.71"
 async-trait = "0.1.68"
 axum = "0.6.20"
 base64 = "0.21.4"
+bs58 = "0.5.0"
 bip39 = { version = "2.0.0", features = ["zeroize"] }
 clap = "4.4.7"
 cfg-if = "1.0.0"
@@ -158,7 +161,7 @@ log = "0.4"
 once_cell = "1.7.2"
 parking_lot = "0.12.1"
 rand = "0.8.5"
-reqwest = "0.11.22"
+reqwest = { version = "0.11.22", default_features = false }
 schemars = "0.8.1"
 serde = "1.0.152"
 serde_json = "1.0.91"
@@ -168,7 +171,7 @@ time = "0.3.30"
 thiserror = "1.0.48"
 tokio = "1.33.0"
 tokio-util = "0.7.10"
-tokio-tungstenite = "0.20.1"
+tokio-tungstenite = { version = "0.20.1" }
 tracing = "0.1.37"
 tungstenite = { version = "0.20.1", default-features = false }
 ts-rs = "7.0.0"

clients/native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "nym-client"
-version = "1.1.32"
+version = "1.1.33"
 authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
 description = "Implementation of the Nym Client"
 edition = "2021"
@@ -21,18 +21,19 @@ futures = { workspace = true } # bunch of futures stuff, however, now that I thi
 # and the single instance of abortable we have should really be refactored anyway
 url = { workspace = true }
 
+bs58 = { workspace = true }
 clap = { workspace = true, features = ["cargo", "derive"] }
 dirs = "4.0"
-lazy_static = "1.4.0"
 log = { workspace = true } # self explanatory
-pretty_env_logger = "0.4" # for formatting log messages
 rand = { version = "0.7.3", features = ["wasm-bindgen"] } # rng-related traits + some rng implementation to use
 serde = { workspace = true, features = ["derive"] } # for config serialization/deserialization
 serde_json = { workspace = true }
 thiserror = { workspace = true }
 tap = "1.0.1"
+time = { workspace = true }
 tokio = { workspace = true, features = ["rt-multi-thread", "net", "signal"] } # async runtime
 tokio-tungstenite = { workspace = true }
+zeroize = { workspace = true }
 
 ## internal
 nym-bandwidth-controller = { path = "../../common/bandwidth-controller" }
@@ -50,5 +51,6 @@ nym-task = { path = "../../common/task" }
 nym-topology = { path = "../../common/topology" }
 nym-validator-client = { path = "../../common/client-libs/validator-client", features = ["http-client"] }
 nym-client-websocket-requests = { path = "websocket-requests" }
+nym-id = { path = "../../common/nym-id" }
 
 [dev-dependencies]

clients/native/examples/js-examples/websocket/package-lock.json

@@ -2160,9 +2160,9 @@
       }
     },
     "node_modules/ip": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/ip/-/ip-1.1.5.tgz",
-      "integrity": "sha1-vd7XARQpCCjAoDnnLvJfWq7ENUo=",
+      "version": "1.1.9",
+      "resolved": "https://registry.npmjs.org/ip/-/ip-1.1.9.tgz",
+      "integrity": "sha512-cyRxvOEpNHNtchU3Ln9KC/auJgup87llfQpQ+t5ghoC/UhL16SWzbueiCsdTnWmqAWl7LadfuwhlqmtOaqMHdQ==",
       "dev": true
     },
     "node_modules/ipaddr.js": {
@@ -6157,9 +6157,9 @@
       "dev": true
     },
     "ip": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/ip/-/ip-1.1.5.tgz",
-      "integrity": "sha1-vd7XARQpCCjAoDnnLvJfWq7ENUo=",
+      "version": "1.1.9",
+      "resolved": "https://registry.npmjs.org/ip/-/ip-1.1.9.tgz",
+      "integrity": "sha512-cyRxvOEpNHNtchU3Ln9KC/auJgup87llfQpQ+t5ghoC/UhL16SWzbueiCsdTnWmqAWl7LadfuwhlqmtOaqMHdQ==",
       "dev": true
     },
     "ipaddr.js": {

clients/native/src/commands/import_credential.rs

@@ -0,0 +1,54 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::commands::try_load_current_config;
+use crate::error::ClientError;
+use clap::ArgGroup;
+
+use nym_id::import_credential;
+use std::fs;
+use std::path::PathBuf;
+
+fn parse_encoded_credential_data(raw: &str) -> bs58::decode::Result<Vec<u8>> {
+    bs58::decode(raw).into_vec()
+}
+
+#[derive(clap::Args)]
+#[clap(group(ArgGroup::new("cred_data").required(true)))]
+pub(crate) struct Args {
+    /// Id of client that is going to import the credential
+    #[clap(long)]
+    pub id: String,
+
+    /// Explicitly provide the encoded credential data (as base58)
+    #[clap(long, group = "cred_data", value_parser = parse_encoded_credential_data)]
+    pub(crate) credential_data: Option<Vec<u8>>,
+
+    /// Specifies the path to file containing binary credential data
+    #[clap(long, group = "cred_data")]
+    pub(crate) credential_path: Option<PathBuf>,
+
+    // currently hidden as there exists only a single serialization standard
+    #[clap(long, hide = true)]
+    pub(crate) version: Option<u8>,
+}
+
+pub(crate) async fn execute(args: Args) -> Result<(), ClientError> {
+    let config = try_load_current_config(&args.id)?;
+
+    let credentials_store = nym_credential_storage::initialise_persistent_storage(
+        &config.storage_paths.common_paths.credentials_database,
+    )
+    .await;
+
+    let raw_credential = match args.credential_data {
+        Some(data) => data,
+        None => {
+            // SAFETY: one of those arguments must have been set
+            fs::read(args.credential_path.unwrap())?
+        }
+    };
+
+    import_credential(credentials_store, raw_credential, args.version).await?;
+    Ok(())
+}

clients/native/src/commands/mod.rs

@@ -8,7 +8,6 @@ use crate::client::config::{BaseClientConfig, Config};
 use crate::error::ClientError;
 use clap::CommandFactory;
 use clap::{Parser, Subcommand};
-use lazy_static::lazy_static;
 use log::{error, info};
 use nym_bin_common::bin_info;
 use nym_bin_common::completions::{fig_generate, ArgShell};
@@ -21,18 +20,16 @@ use nym_client_core::error::ClientCoreError;
 use nym_config::OptionalSet;
 use std::error::Error;
 use std::net::IpAddr;
+use std::sync::OnceLock;
 
 pub(crate) mod build_info;
+pub(crate) mod import_credential;
 pub(crate) mod init;
 pub(crate) mod run;
 
-lazy_static! {
-    pub static ref PRETTY_BUILD_INFORMATION: String = bin_info!().pretty_print();
-}
-
-// Helper for passing LONG_VERSION to clap
 fn pretty_build_info_static() -> &'static str {
-    &PRETTY_BUILD_INFORMATION
+    static PRETTY_BUILD_INFORMATION: OnceLock<String> = OnceLock::new();
+    PRETTY_BUILD_INFORMATION.get_or_init(|| bin_info!().pretty_print())
 }
 
 #[derive(Parser)]
@@ -58,6 +55,9 @@ pub(crate) enum Commands {
     /// Run the Nym client with provided configuration client optionally overriding set parameters
     Run(run::Run),
 
+    /// Import a pre-generated credential
+    ImportCredential(import_credential::Args),
+
     /// Show build information of this binary
     BuildInfo(build_info::BuildInfo),
 
@@ -86,6 +86,7 @@ pub(crate) async fn execute(args: Cli) -> Result<(), Box<dyn Error + Send + Sync
     match args.command {
         Commands::Init(m) => init::execute(m).await?,
         Commands::Run(m) => run::execute(m).await?,
+        Commands::ImportCredential(m) => import_credential::execute(m).await?,
         Commands::BuildInfo(m) => build_info::execute(m),
         Commands::Completions(s) => s.generate(&mut Cli::command(), bin_name),
         Commands::GenerateFigSpec => fig_generate(&mut Cli::command(), bin_name),

clients/native/src/error.rs

@@ -1,11 +1,13 @@
 use nym_client_core::error::ClientCoreError;
 
+use nym_id::NymIdError;
+
 #[derive(thiserror::Error, Debug)]
 pub enum ClientError {
     #[error("I/O error: {0}")]
     IoError(#[from] std::io::Error),
 
-    #[error("client-core error: {0}")]
+    #[error(transparent)]
     ClientCoreError(#[from] ClientCoreError),
 
     #[error("Failed to load config for: {0}")]
@@ -20,4 +22,7 @@ pub enum ClientError {
 
     #[error("Attempted to start the client in invalid socket mode")]
     InvalidSocketMode,
+
+    #[error(transparent)]
+    NymIdError(#[from] NymIdError),
 }

clients/socks5/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "nym-socks5-client"
-version = "1.1.32"
+version = "1.1.33"
 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"
@@ -8,17 +8,18 @@ rust-version = "1.56"
 license.workspace = true
 
 [dependencies]
+bs58 = { workspace = true }
 clap = { workspace = true, features = ["cargo", "derive"] }
-lazy_static = "1.4.0"
 log = { workspace = true }
-pretty_env_logger = "0.4"
 serde = { workspace = true, features = ["derive"] } # for config serialization/deserialization
 serde_json = { workspace = true }
 tap = "1.0.1"
 thiserror = { workspace = true }
 tokio = { version = "1.24.1", features = ["rt-multi-thread", "net", "signal"] }
 rand = "0.7.3"
+time = { workspace = true }
 url = { workspace = true }
+zeroize = { workspace = true }
 
 # internal
 nym-bin-common = { path = "../../common/bin-common", features = ["output_format"] }
@@ -33,7 +34,9 @@ nym-sphinx = { path = "../../common/nymsphinx" }
 nym-ordered-buffer = { path = "../../common/socks5/ordered-buffer" }
 nym-pemstore = { path = "../../common/pemstore" }
 nym-topology = { path = "../../common/topology" }
+nym-topology-control = { path = "../../common/topology-control" }
 nym-socks5-client-core = { path = "../../common/socks5-client-core" }
+nym-id = { path = "../../common/nym-id" }
 
 [features]
 default = []

clients/socks5/src/commands/import_credential.rs

@@ -0,0 +1,54 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::commands::try_load_current_config;
+use crate::error::Socks5ClientError;
+use clap::ArgGroup;
+
+use nym_id::import_credential;
+use std::fs;
+use std::path::PathBuf;
+
+fn parse_encoded_credential_data(raw: &str) -> bs58::decode::Result<Vec<u8>> {
+    bs58::decode(raw).into_vec()
+}
+
+#[derive(clap::Args)]
+#[clap(group(ArgGroup::new("cred_data").required(true)))]
+pub(crate) struct Args {
+    /// Id of client that is going to import the credential
+    #[clap(long)]
+    pub id: String,
+
+    /// Explicitly provide the encoded credential data (as base58)
+    #[clap(long, group = "cred_data", value_parser = parse_encoded_credential_data)]
+    pub(crate) credential_data: Option<Vec<u8>>,
+
+    /// Specifies the path to file containing binary credential data
+    #[clap(long, group = "cred_data")]
+    pub(crate) credential_path: Option<PathBuf>,
+
+    // currently hidden as there exists only a single serialization standard
+    #[clap(long, hide = true)]
+    pub(crate) version: Option<u8>,
+}
+
+pub(crate) async fn execute(args: Args) -> Result<(), Socks5ClientError> {
+    let config = try_load_current_config(&args.id)?;
+
+    let credentials_store = nym_credential_storage::initialise_persistent_storage(
+        &config.storage_paths.common_paths.credentials_database,
+    )
+    .await;
+
+    let raw_credential = match args.credential_data {
+        Some(data) => data,
+        None => {
+            // SAFETY: one of those arguments must have been set
+            fs::read(args.credential_path.unwrap())?
+        }
+    };
+
+    import_credential(credentials_store, raw_credential, args.version).await?;
+    Ok(())
+}

clients/socks5/src/commands/mod.rs

@@ -9,7 +9,6 @@ use crate::config::{BaseClientConfig, Config, SocksClientPaths};
 use crate::error::Socks5ClientError;
 use clap::CommandFactory;
 use clap::{Parser, Subcommand};
-use lazy_static::lazy_static;
 use log::{error, info};
 use nym_bin_common::bin_info;
 use nym_bin_common::completions::{fig_generate, ArgShell};
@@ -17,25 +16,23 @@ use nym_client_core::client::base_client::storage::gateway_details::{
     OnDiskGatewayDetails, PersistedGatewayDetails,
 };
 use nym_client_core::client::key_manager::persistence::OnDiskKeys;
-use nym_client_core::client::topology_control::geo_aware_provider::CountryGroup;
-use nym_client_core::config::{GatewayEndpointConfig, GroupBy, TopologyStructure};
+use nym_client_core::config::{GatewayEndpointConfig, TopologyStructure};
 use nym_client_core::error::ClientCoreError;
 use nym_config::OptionalSet;
 use nym_sphinx::params::{PacketSize, PacketType};
+use nym_topology_control::geo_aware_provider::{CountryGroup, GroupBy};
 use std::error::Error;
 use std::net::IpAddr;
+use std::sync::OnceLock;
 
 pub(crate) mod build_info;
+mod import_credential;
 pub mod init;
 pub(crate) mod run;
 
-lazy_static! {
-    pub static ref PRETTY_BUILD_INFORMATION: String = bin_info!().pretty_print();
-}
-
-// Helper for passing LONG_VERSION to clap
 fn pretty_build_info_static() -> &'static str {
-    &PRETTY_BUILD_INFORMATION
+    static PRETTY_BUILD_INFORMATION: OnceLock<String> = OnceLock::new();
+    PRETTY_BUILD_INFORMATION.get_or_init(|| bin_info!().pretty_print())
 }
 
 #[derive(Parser)]
@@ -61,6 +58,9 @@ pub(crate) enum Commands {
     /// Run the Nym client with provided configuration client optionally overriding set parameters
     Run(run::Run),
 
+    /// Import a pre-generated credential
+    ImportCredential(import_credential::Args),
+
     /// Show build information of this binary
     BuildInfo(build_info::BuildInfo),
 
@@ -92,6 +92,7 @@ pub(crate) async fn execute(args: Cli) -> Result<(), Box<dyn Error + Send + Sync
     match args.command {
         Commands::Init(m) => init::execute(m).await?,
         Commands::Run(m) => run::execute(m).await?,
+        Commands::ImportCredential(m) => import_credential::execute(m).await?,
         Commands::BuildInfo(m) => build_info::execute(m),
         Commands::Completions(s) => s.generate(&mut Cli::command(), bin_name),
         Commands::GenerateFigSpec => fig_generate(&mut Cli::command(), bin_name),

clients/socks5/src/commands/run.rs

@@ -12,9 +12,9 @@ use log::*;
 use nym_bin_common::version_checker::is_minor_version_compatible;
 use nym_client_core::cli_helpers::client_run::CommonClientRunArgs;
 use nym_client_core::client::base_client::storage::OnDiskPersistent;
-use nym_client_core::client::topology_control::geo_aware_provider::CountryGroup;
 use nym_socks5_client_core::NymClient;
 use nym_sphinx::addressing::clients::Recipient;
+use nym_topology_control::geo_aware_provider::CountryGroup;
 use std::net::IpAddr;
 
 #[derive(Args, Clone)]

clients/socks5/src/error.rs

@@ -1,5 +1,7 @@
 use nym_client_core::error::ClientCoreError;
 
+use nym_id::NymIdError;
+
 #[derive(thiserror::Error, Debug)]
 pub enum Socks5ClientError {
     #[error("I/O error: {0}")]
@@ -18,6 +20,9 @@ pub enum Socks5ClientError {
     #[error("Fail to bind address")]
     FailToBindAddress,
 
-    #[error("client-core error: {0}")]
+    #[error(transparent)]
     ClientCoreError(#[from] ClientCoreError),
+
+    #[error(transparent)]
+    NymIdError(#[from] NymIdError),
 }

common/bandwidth-controller/src/acquire/mod.rs

@@ -67,7 +67,7 @@ where
 
     let signature =
         obtain_aggregate_signature(&state.voucher, &coconut_api_clients, threshold).await?;
-    let issued = state.voucher.to_issued_credential(signature);
+    let issued = state.voucher.to_issued_credential(signature, epoch_id);
 
     // make sure the data gets zeroized after persisting it
     let credential_data = Zeroizing::new(issued.pack_v1());

common/bandwidth-controller/src/error.rs

@@ -21,6 +21,9 @@ pub enum BandwidthControllerError {
     #[error("There was a credential storage error - {0}")]
     CredentialStorageError(Box<dyn std::error::Error + Send + Sync>),
 
+    #[error("the credential storage does not contain any usable credentials")]
+    NoCredentialsAvailable,
+
     // this should really be fully incorporated into the above, but messing with coconut is the last thing I want to do now
     #[error(transparent)]
     StorageError(#[from] StorageError),

common/bandwidth-controller/src/lib.rs

@@ -3,10 +3,12 @@
 
 use crate::error::BandwidthControllerError;
 use crate::utils::stored_credential_to_issued_bandwidth;
-use log::{error, warn};
+use log::{debug, error, warn};
 use nym_credential_storage::storage::Storage;
+use nym_credentials::coconut::bandwidth::issued::BandwidthCredentialIssuedDataVariant;
 use nym_credentials::coconut::bandwidth::CredentialSpendingData;
 use nym_credentials::coconut::utils::obtain_aggregate_verification_key;
+use nym_credentials::IssuedBandwidthCredential;
 use nym_credentials_interface::VerificationKey;
 use nym_validator_client::coconut::all_coconut_api_clients;
 use nym_validator_client::nym_api::EpochId;
@@ -33,11 +35,67 @@ pub struct PreparedCredential {
     pub credential_id: i64,
 }
 
+pub struct RetrievedCredential {
+    pub credential: IssuedBandwidthCredential,
+    pub credential_id: i64,
+}
+
 impl<C, St: Storage> BandwidthController<C, St> {
     pub fn new(storage: St, client: C) -> Self {
         BandwidthController { storage, client }
     }
 
+    /// Tries to retrieve one of the stored, unused credentials that hasn't yet expired.
+    /// It marks any retrieved intermediate credentials as expired.
+    pub async fn get_next_usable_credential(
+        &self,
+    ) -> Result<RetrievedCredential, BandwidthControllerError>
+    where
+        <St as Storage>::StorageError: Send + Sync + 'static,
+    {
+        loop {
+            let Some(maybe_next) = self
+                .storage
+                .get_next_unspent_credential()
+                .await
+                .map_err(|err| BandwidthControllerError::CredentialStorageError(Box::new(err)))?
+            else {
+                return Err(BandwidthControllerError::NoCredentialsAvailable);
+            };
+            let id = maybe_next.id;
+
+            // try to deserialize it
+            let valid_credential = match stored_credential_to_issued_bandwidth(maybe_next) {
+                // check if it has already expired
+                Ok(credential) => match credential.variant_data() {
+                    BandwidthCredentialIssuedDataVariant::Voucher(_) => {
+                        debug!("credential {id} is a bandwidth voucher");
+                        credential
+                    }
+                    BandwidthCredentialIssuedDataVariant::FreePass(freepass_info) => {
+                        debug!("credential {id} is a free pass");
+                        if freepass_info.expired() {
+                            warn!("the free pass (id: {id}) has already expired! The expiration was set to {}", freepass_info.expiry_date());
+                            self.storage.mark_expired(id).await.map_err(|err| {
+                                BandwidthControllerError::CredentialStorageError(Box::new(err))
+                            })?;
+                            continue;
+                        }
+                        credential
+                    }
+                },
+                Err(err) => {
+                    error!("failed to deserialize credential with id {id}: {err}. it may need to be manually removed from the storage");
+                    return Err(err);
+                }
+            };
+            return Ok(RetrievedCredential {
+                credential: valid_credential,
+                credential_id: id,
+            });
+        }
+    }
+
     pub fn storage(&self) -> &St {
         &self.storage
     }
@@ -51,7 +109,7 @@ impl<C, St: Storage> BandwidthController<C, St> {
         <St as Storage>::StorageError: Send + Sync + 'static,
     {
         let coconut_api_clients = all_coconut_api_clients(&self.client, epoch_id).await?;
-        Ok(obtain_aggregate_verification_key(&coconut_api_clients).await?)
+        Ok(obtain_aggregate_verification_key(&coconut_api_clients)?)
     }
 
     pub async fn prepare_bandwidth_credential(
@@ -61,29 +119,16 @@ impl<C, St: Storage> BandwidthController<C, St> {
         C: DkgQueryClient + Sync + Send,
         <St as Storage>::StorageError: Send + Sync + 'static,
     {
-        let retrieved_credential = self
-            .storage
-            .get_next_unspent_credential()
-            .await
-            .map_err(|err| BandwidthControllerError::CredentialStorageError(Box::new(err)))?;
+        let retrieved_credential = self.get_next_usable_credential().await?;
 
-        let epoch_id = retrieved_credential.epoch_id as EpochId;
-        let credential_id = retrieved_credential.id;
+        let epoch_id = retrieved_credential.credential.epoch_id();
+        let credential_id = retrieved_credential.credential_id;
 
-        let issued_bandwidth = stored_credential_to_issued_bandwidth(retrieved_credential)?;
+        let verification_key = self.get_aggregate_verification_key(epoch_id).await?;
 
-        let verification_key = match self.get_aggregate_verification_key(epoch_id).await {
-            Ok(key) => key,
-            Err(err) => {
-                warn!("failed to obtain master verification key: {err}. Putting the credential back into the database");
-
-                // TODO: ERROR RECOVERY:
-                error!("unimplemented: putting the credential back into the database");
-                return Err(err);
-            }
-        };
-
-        let spend_request = issued_bandwidth.prepare_for_spending(&verification_key)?;
+        let spend_request = retrieved_credential
+            .credential
+            .prepare_for_spending(&verification_key)?;
 
         Ok(PreparedCredential {
             data: spend_request,

common/bin-common/src/build_information/mod.rs

@@ -69,6 +69,35 @@ impl BinaryBuildInformation {
         }
     }
 
+    // Varient where we want to use the metadata generated by vergen in the consuming crate.
+    pub const fn new_with_local_vergen(
+        binary_name: &'static str,
+        build_timestamp: &'static str,
+        build_version: &'static str,
+        commit_sha: &'static str,
+        commit_timestamp: &'static str,
+        commit_branch: &'static str,
+    ) -> Self {
+        let cargo_debug = env!("VERGEN_CARGO_DEBUG");
+        let cargo_profile = if const_str::equal!(cargo_debug, "true") {
+            "debug"
+        } else {
+            "release"
+        };
+
+        BinaryBuildInformation {
+            binary_name,
+            build_timestamp,
+            build_version,
+            commit_sha,
+            commit_timestamp,
+            commit_branch,
+            rustc_version: env!("VERGEN_RUSTC_SEMVER"),
+            rustc_channel: env!("VERGEN_RUSTC_CHANNEL"),
+            cargo_profile,
+        }
+    }
+
     pub fn to_owned(&self) -> BinaryBuildInformationOwned {
         BinaryBuildInformationOwned {
             binary_name: self.binary_name.to_owned(),
@@ -187,3 +216,33 @@ macro_rules! bin_info_owned {
         .to_owned()
     };
 }
+
+// variant that picks up the vergen build information generated by the build.rs in the consumer
+// crate.
+#[macro_export]
+macro_rules! bin_info_local_vergen {
+    () => {
+        $crate::build_information::BinaryBuildInformation::new_with_local_vergen(
+            env!("CARGO_PKG_NAME"),
+            env!("VERGEN_BUILD_TIMESTAMP"),
+            env!("CARGO_PKG_VERSION"),
+            env!("VERGEN_GIT_SHA"),
+            env!("VERGEN_GIT_COMMIT_TIMESTAMP"),
+            env!("VERGEN_GIT_BRANCH"),
+        )
+    };
+}
+
+#[macro_export]
+macro_rules! bin_info_local_vergen_owned {
+    () => {
+        $crate::build_information::BinaryBuildInformation::new_with_local_vergen(
+            env!("CARGO_PKG_NAME"),
+            env!("VERGEN_BUILD_TIMESTAMP"),
+            env!("CARGO_PKG_VERSION"),
+            env!("VERGEN_GIT_SHA"),
+            env!("VERGEN_GIT_COMMIT_TIMESTAMP"),
+            env!("VERGEN_GIT_BRANCH"),
+        )
+    };
+}

common/client-core/Cargo.toml

@@ -42,6 +42,7 @@ nym-nonexhaustive-delayqueue = { path = "../nonexhaustive-delayqueue" }
 nym-sphinx = { path = "../nymsphinx" }
 nym-pemstore = { path = "../pemstore" }
 nym-topology = { path = "../topology", features = ["serializable"] }
+nym-topology-control = { path = "../topology-control" }
 nym-validator-client = { path = "../client-libs/validator-client", default-features = false }
 nym-task = { path = "../task" }
 nym-credential-storage = { path = "../credential-storage" }

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

@@ -3,7 +3,6 @@
 
 use super::packet_statistics_control::PacketStatisticsReporter;
 use super::received_buffer::ReceivedBufferMessage;
-use super::topology_control::geo_aware_provider::GeoAwareTopologyProvider;
 use crate::client::base_client::storage::gateway_details::GatewayDetailsStore;
 use crate::client::base_client::storage::MixnetClientStorage;
 use crate::client::cover_traffic_stream::LoopCoverTrafficStream;
@@ -22,10 +21,6 @@ use crate::client::replies::reply_controller::{ReplyControllerReceiver, ReplyCon
 use crate::client::replies::reply_storage::{
     CombinedReplyStorage, PersistentReplyStorage, ReplyStorageBackend, SentReplyKeys,
 };
-use crate::client::topology_control::nym_api_provider::NymApiTopologyProvider;
-use crate::client::topology_control::{
-    TopologyAccessor, TopologyRefresher, TopologyRefresherConfig,
-};
 use crate::config::{Config, DebugConfig};
 use crate::error::ClientCoreError;
 use crate::init::{
@@ -50,8 +45,12 @@ use nym_task::connections::{ConnectionCommandReceiver, ConnectionCommandSender,
 use nym_task::{TaskClient, TaskHandle};
 use nym_topology::provider_trait::TopologyProvider;
 use nym_topology::HardcodedTopologyProvider;
+use nym_topology_control::geo_aware_provider::GeoAwareTopologyProvider;
+use nym_topology_control::nym_api_provider::NymApiTopologyProvider;
+use nym_topology_control::{TopologyAccessor, TopologyRefresher, TopologyRefresherConfig};
 use nym_validator_client::nyxd::contract_traits::DkgQueryClient;
 use std::fmt::Debug;
+use std::os::raw::c_int as RawFd;
 use std::path::Path;
 use std::sync::Arc;
 use url::Url;
@@ -103,6 +102,12 @@ pub struct ClientState {
     pub shared_lane_queue_lengths: LaneQueueLengths,
     pub reply_controller_sender: ReplyControllerSender,
     pub topology_accessor: TopologyAccessor,
+    pub gateway_connection: GatewayConnection,
+}
+
+#[derive(Clone, Copy, Debug)]
+pub struct GatewayConnection {
+    pub gateway_ws_fd: Option<RawFd>,
 }
 
 pub enum ClientInputStatus {
@@ -666,6 +671,7 @@ where
             shutdown.fork("gateway_transceiver"),
         )
         .await?;
+        let gateway_ws_fd = gateway_transceiver.ws_fd();
 
         let reply_storage = Self::setup_persistent_reply_storage(
             reply_storage_backend,
@@ -759,6 +765,7 @@ where
                 shared_lane_queue_lengths,
                 reply_controller_sender,
                 topology_accessor: shared_topology_accessor,
+                gateway_connection: GatewayConnection { gateway_ws_fd },
             },
             task_handle: shutdown,
         })

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

@@ -3,7 +3,6 @@
 
 use crate::client::mix_traffic::BatchMixMessageSender;
 use crate::client::packet_statistics_control::{PacketStatisticsEvent, PacketStatisticsReporter};
-use crate::client::topology_control::TopologyAccessor;
 use crate::{config, spawn_future};
 use futures::task::{Context, Poll};
 use futures::{Future, Stream, StreamExt};
@@ -13,6 +12,7 @@ use nym_sphinx::addressing::clients::Recipient;
 use nym_sphinx::cover::generate_loop_cover_packet;
 use nym_sphinx::params::{PacketSize, PacketType};
 use nym_sphinx::utils::sample_poisson_duration;
+use nym_topology_control::TopologyAccessor;
 use rand::{rngs::OsRng, CryptoRng, Rng};
 use std::pin::Pin;
 use std::sync::Arc;

common/client-core/src/client/mix_traffic/transceiver.rs

@@ -8,6 +8,7 @@ use nym_gateway_client::GatewayClient;
 pub use nym_gateway_client::{GatewayPacketRouter, PacketRouter};
 use nym_sphinx::forwarding::packet::MixPacket;
 use std::fmt::Debug;
+use std::os::raw::c_int as RawFd;
 use thiserror::Error;
 
 #[cfg(not(target_arch = "wasm32"))]
@@ -25,6 +26,7 @@ fn erase_err<E: std::error::Error + Send + Sync + 'static>(err: E) -> ErasedGate
 /// This combines combines the functionalities of being able to send and receive mix packets.
 pub trait GatewayTransceiver: GatewaySender + GatewayReceiver {
     fn gateway_identity(&self) -> identity::PublicKey;
+    fn ws_fd(&self) -> Option<RawFd>;
 }
 
 /// This trait defines the functionality of sending `MixPacket` into the mixnet,
@@ -66,6 +68,9 @@ impl<G: GatewayTransceiver + ?Sized + Send> GatewayTransceiver for Box<G> {
     fn gateway_identity(&self) -> identity::PublicKey {
         (**self).gateway_identity()
     }
+    fn ws_fd(&self) -> Option<RawFd> {
+        (**self).ws_fd()
+    }
 }
 
 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
@@ -112,6 +117,9 @@ where
     fn gateway_identity(&self) -> identity::PublicKey {
         self.gateway_client.gateway_identity()
     }
+    fn ws_fd(&self) -> Option<RawFd> {
+        self.gateway_client.ws_fd()
+    }
 }
 
 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
@@ -187,6 +195,9 @@ mod nonwasm_sealed {
         fn gateway_identity(&self) -> identity::PublicKey {
             self.local_identity
         }
+        fn ws_fd(&self) -> Option<RawFd> {
+            None
+        }
     }
 
     #[async_trait]
@@ -259,4 +270,7 @@ impl GatewayTransceiver for MockGateway {
     fn gateway_identity(&self) -> identity::PublicKey {
         self.dummy_identity
     }
+    fn ws_fd(&self) -> Option<RawFd> {
+        None
+    }
 }

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

@@ -11,5 +11,4 @@ pub(crate) mod packet_statistics_control;
 pub mod real_messages_control;
 pub mod received_buffer;
 pub mod replies;
-pub mod topology_control;
 pub(crate) mod transmission_buffer;

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

@@ -266,11 +266,11 @@ impl std::ops::Div<f64> for PacketRates {
 impl PacketRates {
     fn summary(&self) -> String {
         format!(
-            "rx: {}/s (real: {}/s), tx: {}/s (real: {}/s)",
-            bibytes2(self.real_packets_received_size + self.cover_packets_received_size),
+            "down: {}/s, up: {}/s (cover down: {}/s, cover up: {}/s)",
             bibytes2(self.real_packets_received_size),
-            bibytes2(self.real_packets_sent_size + self.cover_packets_sent_size),
             bibytes2(self.real_packets_sent_size),
+            bibytes2(self.cover_packets_received_size),
+            bibytes2(self.cover_packets_sent_size),
         )
     }
 
@@ -288,6 +288,7 @@ impl PacketRates {
     }
 }
 
+#[derive(Debug)]
 pub(crate) enum PacketStatisticsEvent {
     // The real packets sent. Recall that acks are sent by the gateway, so it's not included here.
     RealPacketSent(usize),
@@ -443,7 +444,11 @@ impl PacketStatisticsControl {
             // Check what the number of retransmissions was during the recording window
             if let Some((_, start_stats)) = self.history.front() {
                 let delta = self.stats.clone() - start_stats.clone();
-                log::info!("retransmissions: {}", delta.retransmissions_queued,);
+                log::info!(
+                    "mix packet retransmissions/real mix packets: {}/{}",
+                    delta.retransmissions_queued,
+                    delta.real_packets_queued,
+                );
             } else {
                 log::warn!("Unable to check retransmissions during recording window");
             }

common/client-core/src/client/real_messages_control/message_handler.rs

@@ -7,7 +7,6 @@ use crate::client::real_messages_control::real_traffic_stream::{
 };
 use crate::client::real_messages_control::{AckActionSender, Action};
 use crate::client::replies::reply_storage::{ReceivedReplySurbsMap, SentReplyKeys, UsedSenderTags};
-use crate::client::topology_control::{TopologyAccessor, TopologyReadPermit};
 use log::{debug, error, info, trace, warn};
 use nym_sphinx::acknowledgements::AckKey;
 use nym_sphinx::addressing::clients::Recipient;
@@ -20,6 +19,7 @@ use nym_sphinx::preparer::{MessagePreparer, PreparedFragment};
 use nym_sphinx::Delay;
 use nym_task::connections::TransmissionLane;
 use nym_topology::{NymTopology, NymTopologyError};
+use nym_topology_control::{TopologyAccessor, TopologyReadPermit};
 use rand::{CryptoRng, Rng};
 use std::collections::HashMap;
 use std::sync::Arc;

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

@@ -17,7 +17,6 @@ use crate::{
     client::{
         inbound_messages::InputMessageReceiver, mix_traffic::BatchMixMessageSender,
         real_messages_control::acknowledgement_control::AcknowledgementControllerConnectors,
-        topology_control::TopologyAccessor,
     },
     spawn_future,
 };
@@ -28,6 +27,7 @@ use nym_sphinx::acknowledgements::AckKey;
 use nym_sphinx::addressing::clients::Recipient;
 use nym_sphinx::params::PacketType;
 use nym_task::connections::{ConnectionCommandReceiver, LaneQueueLengths};
+use nym_topology_control::TopologyAccessor;
 use rand::{rngs::OsRng, CryptoRng, Rng};
 use std::sync::Arc;
 

common/client-core/src/client/real_messages_control/real_traffic_stream.rs

@@ -5,7 +5,6 @@ use self::sending_delay_controller::SendingDelayController;
 use crate::client::mix_traffic::BatchMixMessageSender;
 use crate::client::packet_statistics_control::{PacketStatisticsEvent, PacketStatisticsReporter};
 use crate::client::real_messages_control::acknowledgement_control::SentPacketNotificationSender;
-use crate::client::topology_control::TopologyAccessor;
 use crate::client::transmission_buffer::TransmissionBuffer;
 use crate::config;
 use futures::task::{Context, Poll};
@@ -22,6 +21,7 @@ use nym_sphinx::utils::sample_poisson_duration;
 use nym_task::connections::{
     ConnectionCommand, ConnectionCommandReceiver, ConnectionId, LaneQueueLengths, TransmissionLane,
 };
+use nym_topology_control::TopologyAccessor;
 use rand::{CryptoRng, Rng};
 use std::pin::Pin;
 use std::sync::Arc;

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

@@ -1,14 +1,12 @@
 // Copyright 2021-2023 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::{client::topology_control::geo_aware_provider::CountryGroup, error::ClientCoreError};
+use crate::error::ClientCoreError;
 use nym_config::defaults::NymNetworkDetails;
 use nym_crypto::asymmetric::identity;
 use nym_gateway_client::client::GatewayConfig;
-use nym_sphinx::{
-    addressing::clients::Recipient,
-    params::{PacketSize, PacketType},
-};
+use nym_sphinx::params::{PacketSize, PacketType};
+use nym_topology_control::geo_aware_provider::GroupBy;
 use serde::{Deserialize, Serialize};
 use std::time::Duration;
 use url::Url;
@@ -541,22 +539,6 @@ pub enum TopologyStructure {
     GeoAware(GroupBy),
 }
 
-#[allow(clippy::large_enum_variant)]
-#[derive(Copy, Clone, Debug, PartialEq, Serialize, Deserialize)]
-pub enum GroupBy {
-    CountryGroup(CountryGroup),
-    NymAddress(Recipient),
-}
-
-impl std::fmt::Display for GroupBy {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            GroupBy::CountryGroup(group) => write!(f, "group: {}", group),
-            GroupBy::NymAddress(address) => write!(f, "address: {}", address),
-        }
-    }
-}
-
 impl Default for Topology {
     fn default() -> Self {
         Topology {

common/client-core/src/config/old_config_v1_1_30.rs

@@ -1,15 +1,15 @@
 // Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::client::topology_control::geo_aware_provider::CountryGroup;
 use crate::config::{
-    Acknowledgements, Client, Config, CoverTraffic, DebugConfig, GatewayConnection, GroupBy,
-    ReplySurbs, Topology, TopologyStructure, Traffic,
+    Acknowledgements, Client, Config, CoverTraffic, DebugConfig, GatewayConnection, ReplySurbs,
+    Topology, TopologyStructure, Traffic,
 };
 use nym_sphinx::{
     addressing::clients::Recipient,
     params::{PacketSize, PacketType},
 };
+use nym_topology_control::geo_aware_provider::{CountryGroup, GroupBy};
 use serde::{Deserialize, Serialize};
 use std::time::Duration;
 use url::Url;

common/client-libs/gateway-client/Cargo.toml

@@ -48,7 +48,7 @@ features = ["net", "sync", "time"]
 workspace = true
 # the choice of this particular tls feature was arbitrary;
 # if you reckon a different one would be more appropriate, feel free to change it
-features = ["native-tls"]
+# features = ["native-tls"]
 
 # wasm-only dependencies
 [target."cfg(target_arch = \"wasm32\")".dependencies.wasm-bindgen]

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

@@ -6,7 +6,7 @@ use crate::packet_router::PacketRouter;
 pub use crate::packet_router::{
     AcknowledgementReceiver, AcknowledgementSender, MixnetMessageReceiver, MixnetMessageSender,
 };
-use crate::socket_state::{PartiallyDelegated, SocketState};
+use crate::socket_state::{ws_fd, PartiallyDelegated, SocketState};
 use crate::traits::GatewayPacketRouter;
 use crate::{cleanup_socket_message, try_decrypt_binary_message};
 use futures::{SinkExt, StreamExt};
@@ -20,12 +20,12 @@ use nym_gateway_requests::authentication::encrypted_address::EncryptedAddressByt
 use nym_gateway_requests::iv::IV;
 use nym_gateway_requests::registration::handshake::{client_handshake, SharedKeys};
 use nym_gateway_requests::{
-    BinaryRequest, ClientControlRequest, ServerResponse, CURRENT_PROTOCOL_VERSION,
+    BinaryRequest, ClientControlRequest, ServerResponse, CREDENTIAL_UPDATE_V1_PROTOCOL_VERSION,
+    CURRENT_PROTOCOL_VERSION,
 };
 use nym_network_defaults::{REMAINING_BANDWIDTH_THRESHOLD, TOKENS_TO_BURN};
 use nym_sphinx::forwarding::packet::MixPacket;
 use nym_task::TaskClient;
-use nym_validator_client::nym_api::EpochId;
 use nym_validator_client::nyxd::contract_traits::DkgQueryClient;
 use rand::rngs::OsRng;
 use std::convert::TryFrom;
@@ -33,11 +33,15 @@ use std::sync::Arc;
 use std::time::Duration;
 use tungstenite::protocol::Message;
 
+#[cfg(unix)]
+use std::os::fd::RawFd;
 #[cfg(not(target_arch = "wasm32"))]
 use tokio::time::sleep;
 #[cfg(not(target_arch = "wasm32"))]
 use tokio_tungstenite::connect_async;
 
+#[cfg(not(unix))]
+use std::os::raw::c_int as RawFd;
 #[cfg(target_arch = "wasm32")]
 use wasm_utils::websocket::JSWebsocket;
 #[cfg(target_arch = "wasm32")]
@@ -153,6 +157,14 @@ impl<C, St> GatewayClient<C, St> {
         self.gateway_identity
     }
 
+    pub fn ws_fd(&self) -> Option<RawFd> {
+        match &self.connection {
+            SocketState::Available(conn) => ws_fd(conn.as_ref()),
+            SocketState::PartiallyDelegated(conn) => conn.ws_fd(),
+            _ => None,
+        }
+    }
+
     pub fn remaining_bandwidth(&self) -> i64 {
         self.bandwidth_remaining
     }
@@ -383,6 +395,8 @@ impl<C, St> GatewayClient<C, St> {
         &self,
         gateway_protocol: Option<u8>,
     ) -> Result<(), GatewayClientError> {
+        debug!("gateway protocol: {gateway_protocol:?}, ours: {CURRENT_PROTOCOL_VERSION}");
+
         // right now there are no failure cases here, but this might change in the future
         match gateway_protocol {
             None => {
@@ -492,6 +506,7 @@ impl<C, St> GatewayClient<C, St> {
                 self.check_gateway_protocol(protocol_version)?;
                 self.authenticated = status;
                 self.bandwidth_remaining = bandwidth_remaining;
+                self.negotiated_protocol = protocol_version;
                 Ok(())
             }
             ServerResponse::Error { message } => Err(GatewayClientError::GatewayError(message)),
@@ -527,14 +542,12 @@ impl<C, St> GatewayClient<C, St> {
     async fn claim_coconut_bandwidth(
         &mut self,
         credential: CredentialSpendingData,
-        epoch_id: EpochId,
     ) -> Result<(), GatewayClientError> {
         let mut rng = OsRng;
         let iv = IV::new_random(&mut rng);
 
         let msg = ClientControlRequest::new_enc_coconut_bandwidth_credential_v2(
             credential,
-            epoch_id,
             self.shared_key.as_ref().unwrap(),
             iv,
         )
@@ -580,6 +593,18 @@ impl<C, St> GatewayClient<C, St> {
             return self.try_claim_testnet_bandwidth().await;
         }
 
+        let Some(gateway_protocol) = self.negotiated_protocol else {
+            return Err(GatewayClientError::OutdatedGatewayCredentialVersion {
+                negotiated_protocol: None,
+            });
+        };
+
+        if gateway_protocol < CREDENTIAL_UPDATE_V1_PROTOCOL_VERSION {
+            return Err(GatewayClientError::OutdatedGatewayCredentialVersion {
+                negotiated_protocol: Some(gateway_protocol),
+            });
+        }
+
         let prepared_credential = self
             .bandwidth_controller
             .as_ref()
@@ -587,7 +612,7 @@ impl<C, St> GatewayClient<C, St> {
             .prepare_bandwidth_credential()
             .await?;
 
-        self.claim_coconut_bandwidth(prepared_credential.data, prepared_credential.epoch_id)
+        self.claim_coconut_bandwidth(prepared_credential.data)
             .await?;
         self.bandwidth_controller
             .as_ref()

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

@@ -47,6 +47,9 @@ pub enum GatewayClientError {
     #[error("Credential could not be serialized")]
     SerializeCredential,
 
+    #[error("can not spend bandwidth credential with the gateway as it's using outdated protocol (version: {negotiated_protocol:?})")]
+    OutdatedGatewayCredentialVersion { negotiated_protocol: Option<u8> },
+
     #[error("Client is not authenticated")]
     NotAuthenticated,
 

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

@@ -11,9 +11,12 @@ use futures::{SinkExt, StreamExt};
 use log::*;
 use nym_gateway_requests::registration::handshake::SharedKeys;
 use nym_task::TaskClient;
+use std::os::raw::c_int as RawFd;
 use std::sync::Arc;
 use tungstenite::Message;
 
+#[cfg(unix)]
+use std::os::fd::AsRawFd;
 #[cfg(not(target_arch = "wasm32"))]
 use tokio::net::TcpStream;
 #[cfg(not(target_arch = "wasm32"))]
@@ -37,9 +40,22 @@ type WsConn = JSWebsocket;
 
 type SplitStreamReceiver = oneshot::Receiver<Result<SplitStream<WsConn>, GatewayClientError>>;
 
+pub(crate) fn ws_fd(_conn: &WsConn) -> Option<RawFd> {
+    #[cfg(unix)]
+    match _conn.get_ref() {
+        MaybeTlsStream::Plain(stream) => Some(stream.as_raw_fd()),
+        &_ => unreachable!(
+            "If tls features are enabled, the inner stream needs to be unpacked into raw fd"
+        ),
+    }
+    #[cfg(not(unix))]
+    None
+}
+
 pub(crate) struct PartiallyDelegated {
     sink_half: SplitSink<WsConn, Message>,
     delegated_stream: (SplitStreamReceiver, oneshot::Sender<()>),
+    ws_fd: Option<RawFd>,
 }
 
 impl PartiallyDelegated {
@@ -92,6 +108,8 @@ impl PartiallyDelegated {
         let (notify_sender, notify_receiver) = oneshot::channel();
         let (stream_sender, stream_receiver) = oneshot::channel();
 
+        let ws_fd = ws_fd(&conn);
+
         let (sink, mut stream) = conn.split();
 
         let mixnet_receiver_future = async move {
@@ -141,11 +159,16 @@ impl PartiallyDelegated {
         tokio::spawn(mixnet_receiver_future);
 
         PartiallyDelegated {
+            ws_fd,
             sink_half: sink,
             delegated_stream: (stream_receiver, notify_sender),
         }
     }
 
+    pub(crate) fn ws_fd(&self) -> Option<RawFd> {
+        self.ws_fd
+    }
+
     // if we want to send a message and don't care about response, we can don't need to reunite the split,
     // the sink itself is enough
     pub(crate) async fn send_without_response(

common/client-libs/mixnet-client/Cargo.toml

@@ -16,3 +16,11 @@ tokio-util = { workspace = true, features = ["codec"] }
 # internal
 nym-sphinx = { path = "../../nymsphinx" }
 nym-task = { path = "../../task" }
+nym-topology-control = { path = "../../topology-control" }
+nym-noise = { path = "../../nymnoise"}
+nym-crypto = { path = "../../crypto" }
+nym-validator-client = { path = "../validator-client"}
+
+[dev-dependencies]
+url = { workspace = true }
+rand = "0.7.3"

common/client-libs/mixnet-client/src/client.rs

@@ -4,11 +4,15 @@
 use futures::channel::mpsc;
 use futures::StreamExt;
 use log::*;
+use nym_crypto::asymmetric::encryption;
+use nym_noise::upgrade_noise_initiator_with_topology;
 use nym_sphinx::addressing::nodes::NymNodeRoutingAddress;
 use nym_sphinx::framing::codec::NymCodec;
 use nym_sphinx::framing::packet::FramedNymPacket;
 use nym_sphinx::params::PacketType;
 use nym_sphinx::NymPacket;
+use nym_topology_control::accessor::TopologyAccessor;
+use nym_validator_client::NymApiClient;
 use std::collections::HashMap;
 use std::io;
 use std::net::SocketAddr;
@@ -59,6 +63,9 @@ pub trait SendWithoutResponse {
 pub struct Client {
     conn_new: HashMap<NymNodeRoutingAddress, ConnectionSender>,
     config: Config,
+    topology_access: TopologyAccessor,
+    api_client: NymApiClient,
+    local_identity: Arc<encryption::KeyPair>,
 }
 
 struct ConnectionSender {
@@ -76,10 +83,18 @@ impl ConnectionSender {
 }
 
 impl Client {
-    pub fn new(config: Config) -> Client {
+    pub fn new(
+        config: Config,
+        topology_access: TopologyAccessor,
+        api_client: NymApiClient,
+        local_identity: Arc<encryption::KeyPair>,
+    ) -> Client {
         Client {
             conn_new: HashMap::new(),
             config,
+            topology_access,
+            api_client,
+            local_identity,
         }
     }
 
@@ -88,25 +103,60 @@ impl Client {
         receiver: mpsc::Receiver<FramedNymPacket>,
         connection_timeout: Duration,
         current_reconnection: &AtomicU32,
+        topology_access: TopologyAccessor,
+        api_client: NymApiClient,
+        local_identity: Arc<encryption::KeyPair>,
     ) {
         let connection_fut = TcpStream::connect(address);
 
         let conn = match tokio::time::timeout(connection_timeout, connection_fut).await {
-            Ok(stream_res) => match stream_res {
-                Ok(stream) => {
-                    debug!("Managed to establish connection to {}", address);
-                    // if we managed to connect, reset the reconnection count (whatever it might have been)
-                    current_reconnection.store(0, Ordering::Release);
-                    Framed::new(stream, NymCodec)
+            Ok(stream_res) => {
+                match stream_res {
+                    Ok(stream) => {
+                        debug!("Managed to establish connection to {}", address);
+                        // if we managed to connect, reset the reconnection count (whatever it might have been)
+                        current_reconnection.store(0, Ordering::Release);
+                        //Get the topology, because we need the keys for the handshake
+                        let Some(topology) = topology_access.current_topology().await else {
+                            error!("Cannot perform Noise handshake to {address}, due to topology error");
+                            return;
+                        };
+
+                        let epoch_id = match api_client.get_current_epoch_id().await {
+                            Ok(id) => id,
+                            Err(err) => {
+                                error!("Cannot perform Noise handshake to {address}, due to epoch id error - {err}");
+                                return;
+                            }
+                        };
+
+                        let noise_stream = match upgrade_noise_initiator_with_topology(
+                            stream,
+                            Default::default(),
+                            &topology,
+                            epoch_id,
+                            local_identity.private_key(),
+                        )
+                        .await
+                        {
+                            Ok(noise_stream) => noise_stream,
+                            Err(err) => {
+                                error!("Failed to perform Noise handshake with {address} - {err}");
+                                return;
+                            }
+                        };
+                        debug!("Noise initiator handshake completed for {:?}", address);
+                        Framed::new(noise_stream, NymCodec)
+                    }
+                    Err(err) => {
+                        debug!(
+                            "failed to establish connection to {} (err: {})",
+                            address, err
+                        );
+                        return;
+                    }
                 }
-                Err(err) => {
-                    debug!(
-                        "failed to establish connection to {} (err: {})",
-                        address, err
-                    );
-                    return;
-                }
-            },
+            }
             Err(_) => {
                 debug!(
                     "failed to connect to {} within {:?}",
@@ -175,6 +225,10 @@ impl Client {
         // copy the value before moving into another task
         let initial_connection_timeout = self.config.initial_connection_timeout;
 
+        let topology_access_clone = self.topology_access.clone();
+        let api_client_clone = self.api_client.clone();
+        let local_id_key = self.local_identity.clone();
+
         tokio::spawn(async move {
             // before executing the manager, wait for what was specified, if anything
             if let Some(backoff) = backoff {
@@ -187,6 +241,9 @@ impl Client {
                 receiver,
                 initial_connection_timeout,
                 &current_reconnection_attempt,
+                topology_access_clone,
+                api_client_clone,
+                local_id_key,
             )
             .await
         });
@@ -253,15 +310,23 @@ impl SendWithoutResponse for Client {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use rand::rngs::OsRng;
+    use url::Url;
 
     fn dummy_client() -> Client {
-        Client::new(Config {
-            initial_reconnection_backoff: Duration::from_millis(10_000),
-            maximum_reconnection_backoff: Duration::from_millis(300_000),
-            initial_connection_timeout: Duration::from_millis(1_500),
-            maximum_connection_buffer_size: 128,
-            use_legacy_version: false,
-        })
+        let mut rng = OsRng;
+        Client::new(
+            Config {
+                initial_reconnection_backoff: Duration::from_millis(10_000),
+                maximum_reconnection_backoff: Duration::from_millis(300_000),
+                initial_connection_timeout: Duration::from_millis(1_500),
+                maximum_connection_buffer_size: 128,
+                use_legacy_version: false,
+            },
+            TopologyAccessor::new(),
+            NymApiClient::new(Url::parse("http://dummy.url").unwrap()),
+            Arc::new(encryption::KeyPair::new(&mut rng)),
+        )
     }
 
     #[test]

common/client-libs/mixnet-client/src/forwarder.rs

@@ -5,8 +5,11 @@ use crate::client::{Client, Config, SendWithoutResponse};
 use futures::channel::mpsc;
 use futures::StreamExt;
 use log::*;
+use nym_crypto::asymmetric::encryption;
 use nym_sphinx::forwarding::packet::MixPacket;
-use std::time::Duration;
+use nym_topology_control::accessor::TopologyAccessor;
+use nym_validator_client::NymApiClient;
+use std::sync::Arc;
 
 pub type MixForwardingSender = mpsc::UnboundedSender<MixPacket>;
 type MixForwardingReceiver = mpsc::UnboundedReceiver<MixPacket>;
@@ -21,26 +24,22 @@ pub struct PacketForwarder {
 
 impl PacketForwarder {
     pub fn new(
-        initial_reconnection_backoff: Duration,
-        maximum_reconnection_backoff: Duration,
-        initial_connection_timeout: Duration,
-        maximum_connection_buffer_size: usize,
-        use_legacy_version: bool,
+        client_config: Config,
+        topology_access: TopologyAccessor,
+        api_client: NymApiClient,
+        local_identity: Arc<encryption::KeyPair>,
         shutdown: nym_task::TaskClient,
     ) -> (PacketForwarder, MixForwardingSender) {
-        let client_config = Config::new(
-            initial_reconnection_backoff,
-            maximum_reconnection_backoff,
-            initial_connection_timeout,
-            maximum_connection_buffer_size,
-            use_legacy_version,
-        );
-
         let (packet_sender, packet_receiver) = mpsc::unbounded();
 
         (
             PacketForwarder {
-                mixnet_client: Client::new(client_config),
+                mixnet_client: Client::new(
+                    client_config,
+                    topology_access,
+                    api_client,
+                    local_identity,
+                ),
                 packet_receiver,
                 shutdown,
             },

common/client-libs/validator-client/Cargo.toml

@@ -31,7 +31,6 @@ log = { workspace = true }
 url = { workspace = true, features = ["serde"] }
 tokio = { workspace = true, features = ["sync", "time"] }
 futures = { workspace = true }
-openssl = { version = "^0.10.55", features = ["vendored"], optional = true }
 
 nym-coconut = { path = "../../nymcoconut" }
 nym-network-defaults = { path = "../../network-defaults" }
@@ -90,7 +89,7 @@ required-features = ["http-client"]
 
 [features]
 default = ["http-client"]
-http-client = ["cosmrs/rpc", "openssl"]
+http-client = ["cosmrs/rpc"]
 generate-ts = []
 contract-testing = ["nym-mixnet-contract-common/contract-testing"]
 

common/client-libs/validator-client/src/client.rs

@@ -8,10 +8,12 @@ use crate::{
     nym_api, DirectSigningReqwestRpcValidatorClient, QueryReqwestRpcValidatorClient,
     ReqwestRpcClient, ValidatorClientError,
 };
+use nym_api_requests::coconut::models::FreePassNonceResponse;
 use nym_api_requests::coconut::{
-    BlindSignRequestBody, BlindedSignatureResponse, VerifyCredentialBody, VerifyCredentialResponse,
+    BlindSignRequestBody, BlindedSignatureResponse, FreePassRequest, VerifyCredentialBody,
+    VerifyCredentialResponse,
 };
-use nym_api_requests::models::{DescribedGateway, MixNodeBondAnnotated};
+use nym_api_requests::models::{DescribedGateway, DescribedNymNode, MixNodeBondAnnotated};
 use nym_api_requests::models::{
     GatewayCoreStatusResponse, MixnodeCoreStatusResponse, MixnodeStatusResponse,
     RewardEstimationResponse, StakeSaturationResponse,
@@ -289,6 +291,18 @@ impl NymApiClient {
         Ok(self.nym_api.get_gateways_described().await?)
     }
 
+    pub async fn get_cached_described_nodes(
+        &self,
+    ) -> Result<Vec<DescribedNymNode>, ValidatorClientError> {
+        Ok(self.nym_api.get_nym_nodes_described().await?)
+    }
+
+    pub async fn get_current_epoch_id(
+        &self,
+    ) -> Result<nym_mixnet_contract_common::EpochId, ValidatorClientError> {
+        Ok(self.nym_api.get_current_epoch().await?.current_epoch_id())
+    }
+
     pub async fn get_gateway_core_status_count(
         &self,
         identity: IdentityKeyRef<'_>,
@@ -348,4 +362,15 @@ impl NymApiClient {
             .verify_bandwidth_credential(request_body)
             .await?)
     }
+
+    pub async fn free_pass_nonce(&self) -> Result<FreePassNonceResponse, ValidatorClientError> {
+        Ok(self.nym_api.free_pass_nonce().await?)
+    }
+
+    pub async fn issue_free_pass_credential(
+        &self,
+        request: &FreePassRequest,
+    ) -> Result<BlindedSignatureResponse, ValidatorClientError> {
+        Ok(self.nym_api.free_pass(request).await?)
+    }
 }

common/client-libs/validator-client/src/nym_api/mod.rs

@@ -15,16 +15,16 @@ pub use nym_api_requests::{
         VerifyCredentialBody, VerifyCredentialResponse,
     },
     models::{
-        ComputeRewardEstParam, DescribedGateway, GatewayBondAnnotated, GatewayCoreStatusResponse,
-        GatewayStatusReportResponse, GatewayUptimeHistoryResponse, InclusionProbabilityResponse,
-        MixNodeBondAnnotated, MixnodeCoreStatusResponse, MixnodeStatusReportResponse,
-        MixnodeStatusResponse, MixnodeUptimeHistoryResponse, RewardEstimationResponse,
-        StakeSaturationResponse, UptimeResponse,
+        ComputeRewardEstParam, DescribedGateway, DescribedNymNode, GatewayBondAnnotated,
+        GatewayCoreStatusResponse, GatewayStatusReportResponse, GatewayUptimeHistoryResponse,
+        InclusionProbabilityResponse, MixNodeBondAnnotated, MixnodeCoreStatusResponse,
+        MixnodeStatusReportResponse, MixnodeStatusResponse, MixnodeUptimeHistoryResponse,
+        RewardEstimationResponse, StakeSaturationResponse, UptimeResponse,
     },
 };
 pub use nym_coconut_dkg_common::types::EpochId;
 use nym_mixnet_contract_common::mixnode::MixNodeDetails;
-use nym_mixnet_contract_common::{GatewayBond, IdentityKeyRef, MixId};
+use nym_mixnet_contract_common::{GatewayBond, IdentityKeyRef, Interval, MixId};
 use nym_name_service_common::response::NamesListResponse;
 use nym_service_provider_directory_common::response::ServicesListResponse;
 
@@ -32,6 +32,8 @@ pub mod error;
 pub mod routes;
 
 pub use http_api_client::Client;
+use nym_api_requests::coconut::models::FreePassNonceResponse;
+use nym_api_requests::coconut::FreePassRequest;
 
 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
 #[cfg_attr(not(target_arch = "wasm32"), async_trait)]
@@ -95,6 +97,14 @@ pub trait NymApiClientExt: ApiClient {
         .await
     }
 
+    async fn get_nym_nodes_described(&self) -> Result<Vec<DescribedNymNode>, NymAPIError> {
+        self.get_json(
+            &[routes::API_VERSION, routes::NYM_NODES, routes::DESCRIBED],
+            NO_PARAMS,
+        )
+        .await
+    }
+
     async fn get_active_mixnodes(&self) -> Result<Vec<MixNodeDetails>, NymAPIError> {
         self.get_json(
             &[routes::API_VERSION, routes::MIXNODES, routes::ACTIVE],
@@ -142,6 +152,14 @@ pub trait NymApiClientExt: ApiClient {
         .await
     }
 
+    async fn get_current_epoch(&self) -> Result<Interval, NymAPIError> {
+        self.get_json(
+            &[routes::API_VERSION, routes::EPOCH, routes::CURRENT],
+            NO_PARAMS,
+        )
+        .await
+    }
+
     async fn get_gateway_report(
         &self,
         identity: IdentityKeyRef<'_>,
@@ -373,6 +391,36 @@ pub trait NymApiClientExt: ApiClient {
         .await
     }
 
+    async fn free_pass_nonce(&self) -> Result<FreePassNonceResponse, NymAPIError> {
+        self.get_json(
+            &[
+                routes::API_VERSION,
+                routes::COCONUT_ROUTES,
+                routes::BANDWIDTH,
+                routes::COCONUT_FREE_PASS_NONCE,
+            ],
+            NO_PARAMS,
+        )
+        .await
+    }
+
+    async fn free_pass(
+        &self,
+        request: &FreePassRequest,
+    ) -> Result<BlindedSignatureResponse, NymAPIError> {
+        self.post_json(
+            &[
+                routes::API_VERSION,
+                routes::COCONUT_ROUTES,
+                routes::BANDWIDTH,
+                routes::COCONUT_FREE_PASS,
+            ],
+            NO_PARAMS,
+            request,
+        )
+        .await
+    }
+
     async fn blind_sign(
         &self,
         request_body: &BlindSignRequestBody,

common/client-libs/validator-client/src/nym_api/routes.rs

@@ -6,8 +6,12 @@ use nym_network_defaults::NYM_API_VERSION;
 pub const API_VERSION: &str = NYM_API_VERSION;
 pub const MIXNODES: &str = "mixnodes";
 pub const GATEWAYS: &str = "gateways";
+pub const NYM_NODES: &str = "nym-nodes";
 pub const DESCRIBED: &str = "described";
 
+pub const EPOCH: &str = "epoch";
+pub const CURRENT: &str = "current";
+
 pub const DETAILED: &str = "detailed";
 pub const DETAILED_UNFILTERED: &str = "detailed-unfiltered";
 pub const ACTIVE: &str = "active";
@@ -16,6 +20,7 @@ pub const COCONUT_ROUTES: &str = "coconut";
 pub const BANDWIDTH: &str = "bandwidth";
 
 pub const COCONUT_FREE_PASS: &str = "free-pass";
+pub const COCONUT_FREE_PASS_NONCE: &str = "free-pass-nonce";
 pub const COCONUT_BLIND_SIGN: &str = "blind-sign";
 pub const COCONUT_VERIFY_BANDWIDTH_CREDENTIAL: &str = "verify-bandwidth-credential";
 pub const COCONUT_EPOCH_CREDENTIALS: &str = "epoch-credentials";

common/client-libs/validator-client/src/nyxd/contract_traits/dkg_query_client.rs

@@ -7,19 +7,20 @@ use crate::nyxd::error::NyxdError;
 use crate::nyxd::CosmWasmClient;
 use async_trait::async_trait;
 use cosmrs::AccountId;
-use nym_coconut_dkg_common::types::ChunkIndex;
+use cosmwasm_std::Addr;
+use log::trace;
+use nym_coconut_dkg_common::types::{ChunkIndex, NodeIndex, StateAdvanceResponse};
 use serde::Deserialize;
 
+use nym_coconut_dkg_common::dealer::RegisteredDealerDetails;
 pub use nym_coconut_dkg_common::{
-    dealer::{DealerDetailsResponse, PagedDealerResponse},
+    dealer::{DealerDetailsResponse, PagedDealerIndexResponse, PagedDealerResponse},
     dealing::{
         DealerDealingsStatusResponse, DealingChunkResponse, DealingChunkStatusResponse,
         DealingMetadataResponse, DealingStatusResponse,
     },
     msg::QueryMsg as DkgQueryMsg,
-    types::{
-        DealerDetails, DealingIndex, Epoch, EpochId, EpochState, InitialReplacementData, State,
-    },
+    types::{DealerDetails, DealingIndex, Epoch, EpochId, EpochState, State},
     verification_key::{ContractVKShare, PagedVKSharesResponse, VkShareResponse},
 };
 
@@ -40,13 +41,25 @@ pub trait DkgQueryClient {
         self.query_dkg_contract(request).await
     }
 
+    async fn can_advance_state(&self) -> Result<StateAdvanceResponse, NyxdError> {
+        let request = DkgQueryMsg::CanAdvanceState {};
+        self.query_dkg_contract(request).await
+    }
+
     async fn get_current_epoch_threshold(&self) -> Result<Option<u64>, NyxdError> {
         let request = DkgQueryMsg::GetCurrentEpochThreshold {};
         self.query_dkg_contract(request).await
     }
 
-    async fn get_initial_dealers(&self) -> Result<Option<InitialReplacementData>, NyxdError> {
-        let request = DkgQueryMsg::GetInitialDealers {};
+    async fn get_registered_dealer_details(
+        &self,
+        address: &AccountId,
+        epoch_id: Option<EpochId>,
+    ) -> Result<RegisteredDealerDetails, NyxdError> {
+        let request = DkgQueryMsg::GetRegisteredDealer {
+            dealer_address: address.to_string(),
+            epoch_id,
+        };
         self.query_dkg_contract(request).await
     }
 
@@ -69,12 +82,12 @@ pub trait DkgQueryClient {
         self.query_dkg_contract(request).await
     }
 
-    async fn get_past_dealers_paged(
+    async fn get_dealer_indices_paged(
         &self,
         start_after: Option<String>,
         limit: Option<u32>,
-    ) -> Result<PagedDealerResponse, NyxdError> {
-        let request = DkgQueryMsg::GetPastDealers { start_after, limit };
+    ) -> Result<PagedDealerIndexResponse, NyxdError> {
+        let request = DkgQueryMsg::GetDealerIndices { start_after, limit };
         self.query_dkg_contract(request).await
     }
 
@@ -190,8 +203,8 @@ pub trait PagedDkgQueryClient: DkgQueryClient {
         collect_paged!(self, get_current_dealers_paged, dealers)
     }
 
-    async fn get_all_past_dealers(&self) -> Result<Vec<DealerDetails>, NyxdError> {
-        collect_paged!(self, get_past_dealers_paged, dealers)
+    async fn get_all_dealer_indices(&self) -> Result<Vec<(Addr, NodeIndex)>, NyxdError> {
+        collect_paged!(self, get_dealer_indices_paged, indices)
     }
 
     async fn get_all_verification_key_shares(
@@ -218,6 +231,7 @@ where
         let dkg_contract_address = &self
             .dkg_contract_address()
             .ok_or_else(|| NyxdError::unavailable_contract_address("dkg contract"))?;
+        trace!("using the following dkg contract: {dkg_contract_address}");
         self.query_contract_smart(dkg_contract_address, &query)
             .await
     }
@@ -238,18 +252,24 @@ mod tests {
         match msg {
             DkgQueryMsg::GetState {} => client.get_state().ignore(),
             DkgQueryMsg::GetCurrentEpochState {} => client.get_current_epoch().ignore(),
+            DkgQueryMsg::CanAdvanceState {} => client.can_advance_state().ignore(),
             DkgQueryMsg::GetCurrentEpochThreshold {} => {
                 client.get_current_epoch_threshold().ignore()
             }
-            DkgQueryMsg::GetInitialDealers {} => client.get_initial_dealers().ignore(),
+            DkgQueryMsg::GetRegisteredDealer {
+                dealer_address,
+                epoch_id,
+            } => client
+                .get_registered_dealer_details(&dealer_address.parse().unwrap(), epoch_id)
+                .ignore(),
             DkgQueryMsg::GetDealerDetails { dealer_address } => client
                 .get_dealer_details(&dealer_address.parse().unwrap())
                 .ignore(),
             DkgQueryMsg::GetCurrentDealers { limit, start_after } => client
                 .get_current_dealers_paged(start_after, limit)
                 .ignore(),
-            DkgQueryMsg::GetPastDealers { limit, start_after } => {
-                client.get_past_dealers_paged(start_after, limit).ignore()
+            DkgQueryMsg::GetDealerIndices { limit, start_after } => {
+                client.get_dealer_indices_paged(start_after, limit).ignore()
             }
             DkgQueryMsg::GetDealingStatus {
                 epoch_id,

common/client-libs/validator-client/src/nyxd/contract_traits/dkg_signing_client.rs

@@ -39,13 +39,6 @@ pub trait DkgSigningClient {
             .await
     }
 
-    async fn surpass_threshold(&self, fee: Option<Fee>) -> Result<ExecuteResult, NyxdError> {
-        let req = DkgExecuteMsg::SurpassedThreshold {};
-
-        self.execute_dkg_contract(fee, req, "surpass DKG threshold".to_string(), vec![])
-            .await
-    }
-
     async fn register_dealer(
         &self,
         bte_key: EncodedBTEPublicKeyWithProof,
@@ -85,10 +78,9 @@ pub trait DkgSigningClient {
     async fn submit_dealing_chunk(
         &self,
         chunk: PartialContractDealing,
-        resharing: bool,
         fee: Option<Fee>,
     ) -> Result<ExecuteResult, NyxdError> {
-        let req = DkgExecuteMsg::CommitDealingsChunk { chunk, resharing };
+        let req = DkgExecuteMsg::CommitDealingsChunk { chunk };
 
         self.execute_dkg_contract(fee, req, "dealing chunk commitment".to_string(), vec![])
             .await
@@ -130,6 +122,20 @@ pub trait DkgSigningClient {
         )
         .await
     }
+
+    async fn trigger_dkg_reset(&self, fee: Option<Fee>) -> Result<ExecuteResult, NyxdError> {
+        let req = DkgExecuteMsg::TriggerReset {};
+
+        self.execute_dkg_contract(fee, req, "trigger DKG reset".to_string(), vec![])
+            .await
+    }
+
+    async fn trigger_dkg_resharing(&self, fee: Option<Fee>) -> Result<ExecuteResult, NyxdError> {
+        let req = DkgExecuteMsg::TriggerResharing {};
+
+        self.execute_dkg_contract(fee, req, "trigger DKG resharing".to_string(), vec![])
+            .await
+    }
 }
 
 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
@@ -192,8 +198,8 @@ mod tests {
             } => client
                 .submit_dealing_metadata(dealing_index, chunks, resharing, None)
                 .ignore(),
-            DkgExecuteMsg::CommitDealingsChunk { chunk, resharing } => {
-                client.submit_dealing_chunk(chunk, resharing, None).ignore()
+            DkgExecuteMsg::CommitDealingsChunk { chunk } => {
+                client.submit_dealing_chunk(chunk, None).ignore()
             }
             DkgExecuteMsg::CommitVerificationKeyShare { share, resharing } => client
                 .submit_verification_key_share(share, resharing, None)
@@ -201,8 +207,9 @@ mod tests {
             DkgExecuteMsg::VerifyVerificationKeyShare { owner, resharing } => client
                 .verify_verification_key_share(&owner.parse().unwrap(), resharing, None)
                 .ignore(),
-            DkgExecuteMsg::SurpassedThreshold {} => client.surpass_threshold(None).ignore(),
             DkgExecuteMsg::AdvanceEpochState {} => client.advance_dkg_epoch_state(None).ignore(),
+            DkgExecuteMsg::TriggerReset {} => client.trigger_dkg_reset(None).ignore(),
+            DkgExecuteMsg::TriggerResharing {} => client.trigger_dkg_resharing(None).ignore(),
         };
     }
 }

common/client-libs/validator-client/src/nyxd/mod.rs

@@ -16,7 +16,6 @@ use crate::signing::tx_signer::TxSigner;
 use crate::signing::AccountData;
 use crate::{DirectSigningReqwestRpcNyxdClient, QueryReqwestRpcNyxdClient, ReqwestRpcClient};
 use async_trait::async_trait;
-use cosmrs::cosmwasm;
 use cosmrs::tendermint::{abci, evidence::Evidence, Genesis};
 use cosmrs::tx::{Raw, SignDoc};
 use cosmwasm_std::Addr;
@@ -40,7 +39,7 @@ pub use crate::rpc::TendermintRpcClient;
 pub use coin::Coin;
 pub use cosmrs::{
     bank::MsgSend,
-    bip32,
+    bip32, cosmwasm,
     crypto::PublicKey,
     query::{PageRequest, PageResponse},
     tendermint::{
@@ -359,6 +358,10 @@ where
     S: OfflineSigner + Send + Sync,
     NyxdError: From<<S as OfflineSigner>::Error>,
 {
+    pub fn signing_account(&self) -> Result<AccountData, NyxdError> {
+        Ok(self.find_account(&self.address())?)
+    }
+
     pub fn address(&self) -> AccountId {
         match self.client.signer_addresses() {
             Ok(addresses) => addresses[0].clone(),

common/commands/Cargo.toml

@@ -9,12 +9,13 @@ license.workspace = true
 anyhow = { workspace = true }
 base64 = "0.13.0"
 bip39 = { workspace = true }
-bs58 = "0.4"
+bs58 = { workspace = true }
 comfy-table = "6.0.0"
 cfg-if = "1.0.0"
 clap = { workspace = true, features = ["derive"] }
 csv = "1.3.0"
 cw-utils = { workspace = true }
+futures = { workspace = true }
 handlebars = "3.0.1"
 humantime-serde = "1.0"
 inquire = "0.6.2"
@@ -25,9 +26,11 @@ serde = { version = "1.0", features = ["derive"] }
 serde_json = { workspace = true }
 thiserror = { workspace = true }
 time = { workspace = true, features = ["parsing", "formatting"] }
+tokio = { workspace = true, features = ["sync"]}
 toml = "0.5.6"
 url = { workspace = true }
 tap = "1"
+zeroize = { workspace = true }
 
 cosmrs = { workspace = true }
 cosmwasm-std = { workspace = true }
@@ -49,8 +52,10 @@ nym-sphinx = { path = "../../common/nymsphinx" }
 nym-client-core = { path = "../../common/client-core" }
 nym-config = { path = "../../common/config" }
 nym-credentials = { path = "../../common/credentials" }
+nym-credentials-interface = { path = "../../common/credentials-interface" }
 nym-credential-storage = { path = "../../common/credential-storage" }
 nym-credential-utils = { path = "../../common/credential-utils" }
+nym-id = { path = "../nym-id" }
 
 nym-pemstore = { path = "../../common/pemstore", version = "0.3.0" }
 nym-types = { path = "../../common/types" }

common/commands/src/coconut/generate_freepass.rs

@@ -0,0 +1,190 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::context::SigningClient;
+use anyhow::{anyhow, bail};
+use clap::ArgGroup;
+use clap::Parser;
+use futures::StreamExt;
+use log::{error, info};
+use nym_coconut_dkg_common::types::EpochId;
+use nym_credential_utils::utils::block_until_coconut_is_available;
+use nym_credentials::coconut::bandwidth::freepass::MAX_FREE_PASS_VALIDITY;
+use nym_credentials::{
+    obtain_aggregate_verification_key, IssuanceBandwidthCredential, IssuedBandwidthCredential,
+};
+use nym_credentials_interface::VerificationKey;
+use nym_validator_client::coconut::all_coconut_api_clients;
+use nym_validator_client::nyxd::contract_traits::{DkgQueryClient, NymContractsProvider};
+use nym_validator_client::nyxd::CosmWasmClient;
+use nym_validator_client::signing::AccountData;
+use nym_validator_client::CoconutApiClient;
+use std::fs::File;
+use std::io::Write;
+use std::path::PathBuf;
+use std::sync::Arc;
+use time::format_description::well_known::Rfc3339;
+use time::OffsetDateTime;
+use zeroize::Zeroizing;
+
+fn parse_rfc3339_expiration_date(raw: &str) -> Result<OffsetDateTime, time::error::Parse> {
+    OffsetDateTime::parse(raw, &Rfc3339)
+}
+
+#[derive(Debug, Parser)]
+#[clap(group(ArgGroup::new("expiration").required(true)))]
+pub struct Args {
+    /// Specifies the expiration date of the free pass(es)
+    /// Can't be set to more than a week into the future.
+    #[clap(long, group = "expiration", value_parser = parse_rfc3339_expiration_date)]
+    pub(crate) expiration_date: Option<OffsetDateTime>,
+
+    /// The expiration of the free pass(es) expresses as unix timestamp.
+    /// Can't be set to more than a week into the future.
+    #[clap(long, group = "expiration")]
+    pub(crate) expiration_timestamp: Option<i64>,
+
+    /// The number of free passes to issue
+    #[clap(long, default_value = "1")]
+    pub(crate) amount: u64,
+
+    /// Path to the output directory for generated free passes.
+    #[clap(long)]
+    pub(crate) output_dir: PathBuf,
+}
+
+async fn get_freepass(
+    api_clients: Vec<CoconutApiClient>,
+    aggregate_vk: &VerificationKey,
+    threshold: u64,
+    epoch_id: EpochId,
+    signing_account: &AccountData,
+    expiration_date: OffsetDateTime,
+) -> anyhow::Result<IssuedBandwidthCredential> {
+    let issuance_pass = IssuanceBandwidthCredential::new_freepass(Some(expiration_date));
+    let signing_data = issuance_pass.prepare_for_signing();
+
+    let credential_shares = Arc::new(tokio::sync::Mutex::new(Vec::new()));
+
+    futures::stream::iter(api_clients)
+        .for_each_concurrent(None, |client| async {
+            // move the client into the block
+            let client = client;
+            let api_url = client.api_client.api_url();
+
+            info!("contacting {api_url} for blinded free pass");
+
+            match issuance_pass
+                .obtain_partial_freepass_credential(
+                    &client.api_client,
+                    signing_account,
+                    &client.verification_key,
+                    signing_data.clone(),
+                )
+                .await
+            {
+                Ok(partial_credential) => {
+                    credential_shares
+                        .lock()
+                        .await
+                        .push((partial_credential, client.node_id).into());
+                }
+                Err(err) => {
+                    error!("failed to obtain partial free pass from {api_url}: {err}")
+                }
+            }
+        })
+        .await;
+
+    // SAFETY: the futures have completed, so we MUST have the only arc reference
+    #[allow(clippy::unwrap_used)]
+    let credential_shares = Arc::into_inner(credential_shares).unwrap().into_inner();
+
+    if credential_shares.len() < threshold as usize {
+        bail!("we managed to obtain only {} partial credentials while the minimum threshold is {threshold}", credential_shares.len());
+    }
+
+    let signature = issuance_pass.aggregate_signature_shares(aggregate_vk, &credential_shares)?;
+    Ok(issuance_pass.into_issued_credential(signature, epoch_id))
+}
+
+pub async fn execute(args: Args, client: SigningClient) -> anyhow::Result<()> {
+    let address = client.address();
+
+    if !args.output_dir.is_dir() {
+        bail!("the provided output directory is not a directory!");
+    }
+
+    if args.output_dir.read_dir()?.next().is_some() {
+        bail!("the provided output directory is not empty!");
+    }
+
+    let Some(bandwidth_contract) = client.coconut_bandwidth_contract_address() else {
+        bail!("the bandwidth contract address is not set")
+    };
+
+    let Some(bandwidth_admin) = client
+        .get_contract(bandwidth_contract)
+        .await
+        .map(|c| c.contract_info.admin)?
+    else {
+        bail!("the bandwidth contract doesn't have any admin set")
+    };
+
+    // sanity checks since nym-apis will reject invalid requests anyway
+    if address != bandwidth_admin {
+        bail!("the provided mnemonic does not correspond to the current admin of the bandwidth contract")
+    }
+
+    let expiration_date = match args.expiration_date {
+        Some(date) => date,
+        // SAFETY: one of those arguments must have been set
+        None => OffsetDateTime::from_unix_timestamp(args.expiration_timestamp.unwrap())?,
+    };
+
+    let now = OffsetDateTime::now_utc();
+
+    if expiration_date > now + MAX_FREE_PASS_VALIDITY {
+        bail!("the provided free pass request has too long expiry (expiry is set to on {expiration_date})")
+    }
+
+    // issuance start
+    block_until_coconut_is_available(&client).await?;
+
+    let signing_account = client.signing_account()?;
+
+    let epoch_id = client.get_current_epoch().await?.epoch_id;
+    let threshold = client
+        .get_current_epoch_threshold()
+        .await?
+        .ok_or(anyhow!("no threshold available"))?;
+    let api_clients = all_coconut_api_clients(&client, epoch_id).await?;
+
+    if api_clients.len() < threshold as usize {
+        bail!(
+            "we have only {} api clients available while the minimum threshold is {threshold}",
+            api_clients.len()
+        )
+    }
+    let aggregate_vk = obtain_aggregate_verification_key(&api_clients)?;
+
+    for i in 0..args.amount {
+        let human_index = i + 1;
+        info!("trying to obtain free pass {human_index}/{}", args.amount);
+        let free_pass = get_freepass(
+            api_clients.clone(),
+            &aggregate_vk,
+            threshold,
+            epoch_id,
+            &signing_account,
+            expiration_date,
+        )
+        .await?;
+        let credential_data = Zeroizing::new(free_pass.pack_v1());
+        let output = args.output_dir.join(format!("freepass_{i}.nym"));
+        info!("saving the freepass to '{}'", output.display());
+        File::create(output)?.write_all(&credential_data)?;
+    }
+
+    Ok(())
+}

common/commands/src/coconut/import_credential.rs

@@ -0,0 +1,64 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::utils::CommonConfigsWrapper;
+use anyhow::bail;
+use clap::ArgGroup;
+use clap::Parser;
+use nym_credential_storage::initialise_persistent_storage;
+use nym_id::import_credential;
+use std::fs;
+use std::path::PathBuf;
+
+fn parse_encoded_credential_data(raw: &str) -> bs58::decode::Result<Vec<u8>> {
+    bs58::decode(raw).into_vec()
+}
+
+#[derive(Debug, Parser)]
+#[clap(group(ArgGroup::new("cred_data").required(true)))]
+pub struct Args {
+    /// Config file of the client that is supposed to use the credential.
+    #[clap(long)]
+    pub(crate) client_config: PathBuf,
+
+    /// Explicitly provide the encoded credential data (as base58)
+    #[clap(long, group = "cred_data", value_parser = parse_encoded_credential_data)]
+    pub(crate) credential_data: Option<Vec<u8>>,
+
+    /// Specifies the path to file containing binary credential data
+    #[clap(long, group = "cred_data")]
+    pub(crate) credential_path: Option<PathBuf>,
+
+    // currently hidden as there exists only a single serialization standard
+    #[clap(long, hide = true)]
+    pub(crate) version: Option<u8>,
+}
+
+pub async fn execute(args: Args) -> anyhow::Result<()> {
+    let loaded = CommonConfigsWrapper::try_load(args.client_config)?;
+
+    if let Ok(id) = loaded.try_get_id() {
+        println!("loaded config file for client '{id}'");
+    }
+
+    let Ok(credentials_store) = loaded.try_get_credentials_store() else {
+        bail!("the loaded config does not have a credentials store information")
+    };
+
+    println!(
+        "using credentials store at '{}'",
+        credentials_store.display()
+    );
+    let credentials_store = initialise_persistent_storage(credentials_store).await;
+
+    let raw_credential = match args.credential_data {
+        Some(data) => data,
+        None => {
+            // SAFETY: one of those arguments must have been set
+            fs::read(args.credential_path.unwrap())?
+        }
+    };
+
+    import_credential(credentials_store, raw_credential, args.version).await?;
+    Ok(())
+}

common/commands/src/coconut/mod.rs

@@ -3,6 +3,8 @@
 
 use clap::{Args, Subcommand};
 
+pub mod generate_freepass;
+pub mod import_credential;
 pub mod issue_credentials;
 pub mod recover_credentials;
 
@@ -15,6 +17,8 @@ pub struct Coconut {
 
 #[derive(Debug, Subcommand)]
 pub enum CoconutCommands {
+    GenerateFreepass(generate_freepass::Args),
     IssueCredentials(issue_credentials::Args),
     RecoverCredentials(recover_credentials::Args),
+    ImportCredential(import_credential::Args),
 }

common/cosmwasm-smart-contracts/coconut-dkg/src/dealer.rs

@@ -14,20 +14,32 @@ pub struct DealerDetails {
     pub assigned_index: NodeIndex,
 }
 
+#[cw_serde]
+pub struct DealerRegistrationDetails {
+    pub bte_public_key_with_proof: EncodedBTEPublicKeyWithProof,
+    pub ed25519_identity: String,
+    pub announce_address: String,
+}
+
 #[cw_serde]
 #[derive(Copy)]
 pub enum DealerType {
-    Current,
-    Past,
+    Current { assigned_index: NodeIndex },
+    Past { assigned_index: NodeIndex },
     Unknown,
 }
 
 impl DealerType {
     pub fn is_current(&self) -> bool {
-        matches!(&self, DealerType::Current)
+        matches!(&self, DealerType::Current { .. })
     }
 }
 
+#[cw_serde]
+pub struct RegisteredDealerDetails {
+    pub details: Option<DealerRegistrationDetails>,
+}
+
 #[cw_serde]
 pub struct DealerDetailsResponse {
     pub details: Option<DealerDetails>,
@@ -65,3 +77,20 @@ impl PagedDealerResponse {
         }
     }
 }
+
+#[cw_serde]
+pub struct PagedDealerIndexResponse {
+    pub indices: Vec<(Addr, NodeIndex)>,
+
+    /// Field indicating paging information for the following queries if the caller wishes to get further entries.
+    pub start_next_after: Option<Addr>,
+}
+
+impl PagedDealerIndexResponse {
+    pub fn new(indices: Vec<(Addr, NodeIndex)>, start_next_after: Option<Addr>) -> Self {
+        PagedDealerIndexResponse {
+            indices,
+            start_next_after,
+        }
+    }
+}

common/cosmwasm-smart-contracts/coconut-dkg/src/msg.rs

@@ -11,12 +11,15 @@ use cosmwasm_schema::cw_serde;
 
 #[cfg(feature = "schema")]
 use crate::{
-    dealer::{DealerDetailsResponse, PagedDealerResponse},
+    dealer::{
+        DealerDetailsResponse, PagedDealerIndexResponse, PagedDealerResponse,
+        RegisteredDealerDetails,
+    },
     dealing::{
         DealerDealingsStatusResponse, DealingChunkResponse, DealingChunkStatusResponse,
         DealingMetadataResponse, DealingStatusResponse,
     },
-    types::{Epoch, InitialReplacementData, State},
+    types::{Epoch, State, StateAdvanceResponse},
     verification_key::{PagedVKSharesResponse, VkShareResponse},
 };
 #[cfg(feature = "schema")]
@@ -53,7 +56,6 @@ pub enum ExecuteMsg {
 
     CommitDealingsChunk {
         chunk: PartialContractDealing,
-        resharing: bool,
     },
 
     CommitVerificationKeyShare {
@@ -66,9 +68,11 @@ pub enum ExecuteMsg {
         resharing: bool,
     },
 
-    SurpassedThreshold {},
-
     AdvanceEpochState {},
+
+    TriggerReset {},
+
+    TriggerResharing {},
 }
 
 #[cw_serde]
@@ -83,8 +87,14 @@ pub enum QueryMsg {
     #[cfg_attr(feature = "schema", returns(u64))]
     GetCurrentEpochThreshold {},
 
-    #[cfg_attr(feature = "schema", returns(Option<InitialReplacementData>))]
-    GetInitialDealers {},
+    #[cfg_attr(feature = "schema", returns(StateAdvanceResponse))]
+    CanAdvanceState {},
+
+    #[cfg_attr(feature = "schema", returns(RegisteredDealerDetails))]
+    GetRegisteredDealer {
+        dealer_address: String,
+        epoch_id: Option<EpochId>,
+    },
 
     #[cfg_attr(feature = "schema", returns(DealerDetailsResponse))]
     GetDealerDetails { dealer_address: String },
@@ -95,8 +105,8 @@ pub enum QueryMsg {
         start_after: Option<String>,
     },
 
-    #[cfg_attr(feature = "schema", returns(PagedDealerResponse))]
-    GetPastDealers {
+    #[cfg_attr(feature = "schema", returns(PagedDealerIndexResponse))]
+    GetDealerIndices {
         limit: Option<u32>,
         start_after: Option<String>,
     },

common/cosmwasm-smart-contracts/coconut-dkg/src/types.rs

@@ -5,7 +5,7 @@ use cosmwasm_schema::cw_serde;
 use std::fmt::{Display, Formatter};
 use std::str::FromStr;
 
-pub use crate::dealer::{DealerDetails, PagedDealerResponse};
+pub use crate::dealer::{DealerDetails, DealerRegistrationDetails, PagedDealerResponse};
 pub use contracts_common::dealings::ContractSafeBytes;
 pub use cosmwasm_std::{Addr, Coin, Timestamp};
 pub use cw4::Cw4Contract;
@@ -22,9 +22,19 @@ pub type ChunkIndex = u16;
 pub type PartialContractDealingData = ContractSafeBytes;
 
 #[cw_serde]
-pub struct InitialReplacementData {
-    pub initial_dealers: Vec<Addr>,
-    pub initial_height: u64,
+#[derive(Copy, Default)]
+pub struct StateAdvanceResponse {
+    pub current_state: EpochState,
+    pub progress: StateProgress,
+    pub deadline: Option<Timestamp>,
+    pub reached_deadline: bool,
+    pub is_complete: bool,
+}
+
+impl StateAdvanceResponse {
+    pub fn can_advance(&self) -> bool {
+        self.reached_deadline || self.is_complete
+    }
 }
 
 #[cw_serde]
@@ -40,6 +50,26 @@ pub struct TimeConfiguration {
     pub in_progress_time_secs: u64,
 }
 
+impl TimeConfiguration {
+    pub fn state_duration(&self, state: EpochState) -> Option<u64> {
+        match state {
+            EpochState::WaitingInitialisation => None,
+            EpochState::PublicKeySubmission { .. } => Some(self.public_key_submission_time_secs),
+            EpochState::DealingExchange { .. } => Some(self.dealing_exchange_time_secs),
+            EpochState::VerificationKeySubmission { .. } => {
+                Some(self.verification_key_submission_time_secs)
+            }
+            EpochState::VerificationKeyValidation { .. } => {
+                Some(self.verification_key_validation_time_secs)
+            }
+            EpochState::VerificationKeyFinalization { .. } => {
+                Some(self.verification_key_finalization_time_secs)
+            }
+            EpochState::InProgress => Some(self.in_progress_time_secs),
+        }
+    }
+}
+
 impl FromStr for TimeConfiguration {
     type Err = String;
 
@@ -87,13 +117,41 @@ pub struct State {
     pub key_size: u32,
 }
 
+#[cw_serde]
+#[derive(Copy, Default)]
+pub struct StateProgress {
+    /// Counts the number of dealers that have registered in this epoch.
+    // ideally we want to have here all group members
+    pub registered_dealers: u32,
+
+    /// Counts the number of resharing dealers that have registered in this epoch.
+    /// This field is only populated during a resharing exchange.
+    /// It is always <= registered_dealers.
+    pub registered_resharing_dealers: u32,
+
+    /// Counts the number of fully received dealings (i.e. full chunks) from all the allowed dealers.
+    // we expect registered_dealers * state.key_size number of dealings here (each dealer has to submit key_size number of dealings)
+    pub submitted_dealings: u32,
+
+    /// Counts the number of submitted verification key shared from the dealers.
+    // we expect registered_dealers number of keys here
+    pub submitted_key_shares: u32,
+
+    /// Counts the number of verified key shares.
+    // we expect submitted_key_shares number of verified keys here
+    pub verified_keys: u32,
+}
+
 #[cw_serde]
 #[derive(Copy, Default)]
 pub struct Epoch {
     pub state: EpochState,
     pub epoch_id: EpochId,
+    pub state_progress: StateProgress,
     pub time_configuration: TimeConfiguration,
-    pub finish_timestamp: Option<Timestamp>,
+
+    #[serde(alias = "finish_timestamp")]
+    pub deadline: Option<Timestamp>,
 }
 
 impl Epoch {
@@ -103,35 +161,45 @@ impl Epoch {
         time_configuration: TimeConfiguration,
         current_timestamp: Timestamp,
     ) -> Self {
-        let duration = match state {
-            EpochState::WaitingInitialisation => None,
-            EpochState::PublicKeySubmission { .. } => {
-                Some(time_configuration.public_key_submission_time_secs)
-            }
-            EpochState::DealingExchange { .. } => {
-                Some(time_configuration.dealing_exchange_time_secs)
-            }
-            EpochState::VerificationKeySubmission { .. } => {
-                Some(time_configuration.verification_key_submission_time_secs)
-            }
-            EpochState::VerificationKeyValidation { .. } => {
-                Some(time_configuration.verification_key_validation_time_secs)
-            }
-            EpochState::VerificationKeyFinalization { .. } => {
-                Some(time_configuration.verification_key_finalization_time_secs)
-            }
-            EpochState::InProgress => Some(time_configuration.in_progress_time_secs),
-        };
+        let duration = time_configuration.state_duration(state);
+
         Epoch {
             state,
             epoch_id,
+            state_progress: Default::default(),
             time_configuration,
-            finish_timestamp: duration.map(|d| current_timestamp.plus_seconds(d)),
+            deadline: duration.map(|d| current_timestamp.plus_seconds(d)),
         }
     }
 
+    pub fn update(mut self, next_state: EpochState, current_timestamp: Timestamp) -> Self {
+        self.state = next_state;
+        let duration = self.time_configuration.state_duration(next_state);
+        self.deadline = duration.map(|d| current_timestamp.plus_seconds(d));
+
+        self
+    }
+
+    pub fn next_reset(self, current_timestamp: Timestamp) -> Self {
+        Epoch::new(
+            EpochState::PublicKeySubmission { resharing: false },
+            self.epoch_id + 1,
+            self.time_configuration,
+            current_timestamp,
+        )
+    }
+
+    pub fn next_resharing(self, current_timestamp: Timestamp) -> Self {
+        Epoch::new(
+            EpochState::PublicKeySubmission { resharing: true },
+            self.epoch_id + 1,
+            self.time_configuration,
+            current_timestamp,
+        )
+    }
+
     pub fn final_timestamp_secs(&self) -> Option<u64> {
-        let mut finish = self.finish_timestamp?.seconds();
+        let mut finish = self.deadline?.seconds();
         let time_configuration = self.time_configuration;
         let mut curr_epoch_state = self.state;
         while let Some(state) = curr_epoch_state.next() {
@@ -256,4 +324,8 @@ impl EpochState {
     pub fn is_in_progress(&self) -> bool {
         matches!(self, EpochState::InProgress)
     }
+
+    pub fn is_dealing_exchange(&self) -> bool {
+        matches!(self, EpochState::DealingExchange { .. })
+    }
 }

common/cosmwasm-smart-contracts/contracts-common/Cargo.toml

@@ -8,7 +8,7 @@ license = { workspace = true }
 repository = { workspace = true }
 
 [dependencies]
-bs58 = "0.4.0"
+bs58 = { workspace = true }
 cosmwasm-std = { workspace = true }
 cosmwasm-schema = { workspace = true }
 schemars = "0.8"

common/credential-storage/migrations/20240206120000_add_credential_types.sql

@@ -13,5 +13,6 @@ CREATE TABLE coconut_credentials
     credential_type        TEXT    NOT NULL,
     credential_data        BLOB    NOT NULL,
     epoch_id               INTEGER NOT NULL,
-    consumed               BOOLEAN NOT NULL
+    consumed               BOOLEAN NOT NULL,
+    expired                BOOLEAN NOT NULL
 );

common/credential-storage/src/backends/memory.rs

@@ -48,13 +48,18 @@ impl CoconutCredentialManager {
             credential_type,
             epoch_id,
             consumed: false,
+            expired: false,
         })
     }
 
     /// Tries to retrieve one of the stored, unused credentials.
     pub async fn get_next_unspent_credential(&self) -> Option<StoredIssuedCredential> {
         let creds = self.inner.read().await;
-        creds.data.iter().find(|c| !c.consumed).cloned()
+        creds
+            .data
+            .iter()
+            .find(|c| !c.consumed && !c.expired)
+            .cloned()
     }
 
     /// Consumes in the database the specified credential.
@@ -68,4 +73,16 @@ impl CoconutCredentialManager {
             cred.consumed = true;
         }
     }
+
+    /// Marks the specified credential as expired
+    ///
+    /// # Arguments
+    ///
+    /// * `id`: Id of the credential to mark as expired.
+    pub async fn mark_expired(&self, id: i64) {
+        let mut creds = self.inner.write().await;
+        if let Some(cred) = creds.data.get_mut(id as usize) {
+            cred.expired = true;
+        }
+    }
 }

common/credential-storage/src/backends/sqlite.rs

@@ -27,8 +27,8 @@ impl CoconutCredentialManager {
     ) -> Result<(), sqlx::Error> {
         sqlx::query!(
             r#"
-                INSERT INTO coconut_credentials(serialization_revision, credential_type, credential_data, epoch_id, consumed)
-                VALUES (?, ?, ?, ?, false)
+                INSERT INTO coconut_credentials(serialization_revision, credential_type, credential_data, epoch_id, consumed, expired)
+                VALUES (?, ?, ?, ?, false, false)
             "#,
             serialization_revision, credential_type, credential_data, epoch_id
         ).execute(&self.connection_pool).await?;
@@ -38,9 +38,11 @@ impl CoconutCredentialManager {
     pub async fn get_next_unspent_credential(
         &self,
     ) -> Result<Option<StoredIssuedCredential>, sqlx::Error> {
-        sqlx::query_as("SELECT * FROM coconut_credentials WHERE NOT consumed LIMIT 1")
-            .fetch_optional(&self.connection_pool)
-            .await
+        sqlx::query_as(
+            "SELECT * FROM coconut_credentials WHERE NOT consumed AND NOT expired LIMIT 1",
+        )
+        .fetch_optional(&self.connection_pool)
+        .await
     }
 
     /// Consumes in the database the specified credential.
@@ -57,4 +59,19 @@ impl CoconutCredentialManager {
         .await?;
         Ok(())
     }
+
+    /// Marks the specified credential as expired
+    ///
+    /// # Arguments
+    ///
+    /// * `id`: Id of the credential to mark as expired.
+    pub async fn mark_expired(&self, id: i64) -> Result<(), sqlx::Error> {
+        sqlx::query!(
+            "UPDATE coconut_credentials SET expired = TRUE WHERE id = ?",
+            id
+        )
+        .execute(&self.connection_pool)
+        .await?;
+        Ok(())
+    }
 }

common/credential-storage/src/ephemeral_storage.rs

@@ -44,14 +44,11 @@ impl Storage for EphemeralStorage {
 
     async fn get_next_unspent_credential(
         &self,
-    ) -> Result<StoredIssuedCredential, Self::StorageError> {
-        let credential = self
+    ) -> Result<Option<StoredIssuedCredential>, Self::StorageError> {
+        Ok(self
             .coconut_credential_manager
             .get_next_unspent_credential()
-            .await
-            .ok_or(StorageError::NoCredential)?;
-
-        Ok(credential)
+            .await)
     }
 
     async fn consume_coconut_credential(&self, id: i64) -> Result<(), StorageError> {
@@ -61,4 +58,10 @@ impl Storage for EphemeralStorage {
 
         Ok(())
     }
+
+    async fn mark_expired(&self, id: i64) -> Result<(), Self::StorageError> {
+        self.coconut_credential_manager.mark_expired(id).await;
+
+        Ok(())
+    }
 }

common/credential-storage/src/models.rs

@@ -27,6 +27,7 @@ pub struct StoredIssuedCredential {
 
     pub epoch_id: u32,
     pub consumed: bool,
+    pub expired: bool,
 }
 
 pub struct StorableIssuedCredential<'a> {

common/credential-storage/src/persistent_storage.rs

@@ -76,14 +76,11 @@ impl Storage for PersistentStorage {
 
     async fn get_next_unspent_credential(
         &self,
-    ) -> Result<StoredIssuedCredential, Self::StorageError> {
-        let credential = self
+    ) -> Result<Option<StoredIssuedCredential>, Self::StorageError> {
+        Ok(self
             .coconut_credential_manager
             .get_next_unspent_credential()
-            .await?
-            .ok_or(StorageError::NoCredential)?;
-
-        Ok(credential)
+            .await?)
     }
 
     async fn consume_coconut_credential(&self, id: i64) -> Result<(), StorageError> {
@@ -93,4 +90,10 @@ impl Storage for PersistentStorage {
 
         Ok(())
     }
+
+    async fn mark_expired(&self, id: i64) -> Result<(), Self::StorageError> {
+        self.coconut_credential_manager.mark_expired(id).await?;
+
+        Ok(())
+    }
 }

common/credential-storage/src/storage.rs

@@ -14,10 +14,11 @@ pub trait Storage: Send + Sync {
         bandwidth_credential: StorableIssuedCredential<'a>,
     ) -> Result<(), Self::StorageError>;
 
-    /// Tries to retrieve one of the stored, unused credentials.
+    /// Tries to retrieve one of the stored, unused credentials,
+    /// that is also not marked as expired
     async fn get_next_unspent_credential(
         &self,
-    ) -> Result<StoredIssuedCredential, Self::StorageError>;
+    ) -> Result<Option<StoredIssuedCredential>, Self::StorageError>;
 
     /// Marks as consumed in the database the specified credential.
     ///
@@ -25,4 +26,11 @@ pub trait Storage: Send + Sync {
     ///
     /// * `id`: Id of the credential to be consumed.
     async fn consume_coconut_credential(&self, id: i64) -> Result<(), Self::StorageError>;
+
+    /// Marks the specified credential as expired
+    ///
+    /// # Arguments
+    ///
+    /// * `id`: Id of the credential to mark as expired.
+    async fn mark_expired(&self, id: i64) -> Result<(), Self::StorageError>;
 }

common/credential-utils/src/recovery_storage.rs

@@ -53,7 +53,7 @@ impl RecoveryStorage {
 
     pub fn voucher_filename(voucher: &IssuanceBandwidthCredential) -> String {
         let prefix = voucher.typ().to_string();
-        let suffix = voucher.blinded_g1_serial_number_bs58();
+        let suffix = voucher.blinded_serial_number_bs58();
         format!("{prefix}-{suffix}.{DUMPED_VOUCHER_EXTENSION}")
     }
 

common/credential-utils/src/utils.rs

@@ -92,7 +92,7 @@ where
             .as_secs();
 
         if epoch.state.is_final() {
-            if let Some(finish_timestamp) = epoch.finish_timestamp {
+            if let Some(finish_timestamp) = epoch.deadline {
                 if current_timestamp_secs + SAFETY_BUFFER_SECS >= finish_timestamp.seconds() {
                     info!("In the next {} minute(s), a transition will take place in the coconut system. Deposits should be halted in this time for safety reasons.", SAFETY_BUFFER_SECS / 60);
                     exit(0);

common/credentials-interface/src/lib.rs

@@ -10,9 +10,9 @@ use thiserror::Error;
 pub use nym_coconut::{
     aggregate_signature_shares, aggregate_verification_keys, blind_sign, hash_to_scalar, keygen,
     prepare_blind_sign, prove_bandwidth_credential, verify_credential, Attribute, Base58,
-    BlindSignRequest, BlindedSignature, Bytable, CoconutError, KeyPair, Parameters,
-    PrivateAttribute, PublicAttribute, SecretKey, Signature, SignatureShare, VerificationKey,
-    VerifyCredentialRequest,
+    BlindSignRequest, BlindedSerialNumber, BlindedSignature, Bytable, CoconutError, KeyPair,
+    Parameters, PrivateAttribute, PublicAttribute, SecretKey, Signature, SignatureShare,
+    VerificationKey, VerifyCredentialRequest,
 };
 
 pub const VOUCHER_INFO_TYPE: &str = "BandwidthVoucher";
@@ -92,6 +92,9 @@ pub struct CredentialSpendingData {
     pub public_attributes_plain: Vec<String>,
 
     pub typ: CredentialType,
+
+    /// The (DKG) epoch id under which the credential has been issued so that the verifier could use correct verification key for validation.
+    pub epoch_id: u64,
 }
 
 impl CredentialSpendingData {
@@ -126,4 +129,8 @@ impl CredentialSpendingData {
         // the first attribute is variant specific bandwidth encoding, the second one should be the type
         self.public_attributes_plain.first()
     }
+
+    pub fn blinded_serial_number(&self) -> BlindedSerialNumber {
+        self.verify_credential_request.blinded_serial_number()
+    }
 }

common/credentials/src/coconut/bandwidth/freepass.rs

@@ -2,14 +2,19 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::coconut::utils::scalar_serde_helper;
-use nym_credentials_interface::{hash_to_scalar, Attribute, PublicAttribute};
+use crate::error::Error;
+use nym_api_requests::coconut::FreePassRequest;
+use nym_credentials_interface::{
+    hash_to_scalar, Attribute, BlindedSignature, CredentialSigningData, PublicAttribute,
+};
+use nym_validator_client::signing::AccountData;
 use serde::{Deserialize, Serialize};
 use time::{Duration, OffsetDateTime, Time};
 use zeroize::{Zeroize, ZeroizeOnDrop};
 
 pub const MAX_FREE_PASS_VALIDITY: Duration = Duration::WEEK; // 1 week
 
-#[derive(Zeroize, ZeroizeOnDrop, Serialize, Deserialize)]
+#[derive(Debug, Zeroize, ZeroizeOnDrop, Serialize, Deserialize)]
 pub struct FreePassIssuedData {
     /// the plain validity value of this credential expressed as unix timestamp
     #[zeroize(skip)]
@@ -25,6 +30,14 @@ impl<'a> From<&'a FreePassIssuanceData> for FreePassIssuedData {
 }
 
 impl FreePassIssuedData {
+    pub fn expired(&self) -> bool {
+        self.expiry_date <= OffsetDateTime::now_utc()
+    }
+
+    pub fn expiry_date(&self) -> OffsetDateTime {
+        self.expiry_date
+    }
+
     pub fn expiry_date_plain(&self) -> String {
         self.expiry_date.unix_timestamp().to_string()
     }
@@ -76,4 +89,53 @@ impl FreePassIssuanceData {
     pub fn expiry_date_plain(&self) -> String {
         self.expiry_date.unix_timestamp().to_string()
     }
+
+    pub async fn obtain_free_pass_nonce(
+        &self,
+        client: &nym_validator_client::client::NymApiClient,
+    ) -> Result<[u8; 16], Error> {
+        let server_response = client.free_pass_nonce().await?;
+        Ok(server_response.current_nonce)
+    }
+
+    pub fn create_free_pass_request(
+        &self,
+        signing_request: &CredentialSigningData,
+        account_data: &AccountData,
+        issuer_nonce: [u8; 16],
+    ) -> Result<FreePassRequest, Error> {
+        let nonce_signature = account_data
+            .private_key()
+            .sign(&issuer_nonce)
+            .map_err(|_| Error::Secp256k1SignFailure)?;
+
+        Ok(FreePassRequest {
+            cosmos_pubkey: account_data.public_key(),
+            inner_sign_request: signing_request.blind_sign_request.clone(),
+            used_nonce: issuer_nonce,
+            nonce_signature,
+            public_attributes_plain: signing_request.public_attributes_plain.clone(),
+        })
+    }
+
+    pub async fn obtain_blinded_credential(
+        &self,
+        client: &nym_validator_client::client::NymApiClient,
+        request: &FreePassRequest,
+    ) -> Result<BlindedSignature, Error> {
+        let server_response = client.issue_free_pass_credential(request).await?;
+        Ok(server_response.blinded_signature)
+    }
+
+    pub async fn request_blinded_credential(
+        &self,
+        signing_request: &CredentialSigningData,
+        account_data: &AccountData,
+        client: &nym_validator_client::client::NymApiClient,
+    ) -> Result<BlindedSignature, Error> {
+        let signing_nonce = self.obtain_free_pass_nonce(client).await?;
+        let request =
+            self.create_free_pass_request(signing_request, account_data, signing_nonce)?;
+        self.obtain_blinded_credential(client, &request).await
+    }
 }

common/credentials/src/coconut/bandwidth/issuance.rs

@@ -9,13 +9,15 @@ use crate::coconut::bandwidth::{
 };
 use crate::coconut::utils::scalar_serde_helper;
 use crate::error::Error;
-use bls12_381::G1Projective;
 use nym_credentials_interface::{
-    aggregate_signature_shares, hash_to_scalar, prepare_blind_sign, Attribute, Parameters,
-    PrivateAttribute, PublicAttribute, Signature, SignatureShare, VerificationKey,
+    aggregate_signature_shares, hash_to_scalar, prepare_blind_sign, Attribute, BlindedSerialNumber,
+    BlindedSignature, Parameters, PrivateAttribute, PublicAttribute, Signature, SignatureShare,
+    VerificationKey,
 };
 use nym_crypto::asymmetric::{encryption, identity};
+use nym_validator_client::nym_api::EpochId;
 use nym_validator_client::nyxd::{Coin, Hash};
+use nym_validator_client::signing::AccountData;
 use serde::{Deserialize, Serialize};
 use time::OffsetDateTime;
 use zeroize::{Zeroize, ZeroizeOnDrop};
@@ -138,15 +140,14 @@ impl IssuanceBandwidthCredential {
         Self::new(FreePassIssuanceData::new(expiry_date))
     }
 
-    pub fn blind_serial_number_in_g1subgroup(&self) -> G1Projective {
-        bandwidth_credential_params().gen1() * self.serial_number
+    pub fn blind_serial_number(&self) -> BlindedSerialNumber {
+        (bandwidth_credential_params().gen2() * self.serial_number).into()
     }
 
-    // NOT TO BE CONFUSED WITH BLINDED SERIAL NUMBER IN CREDENTIAL ITSELF
-    pub fn blinded_g1_serial_number_bs58(&self) -> String {
+    pub fn blinded_serial_number_bs58(&self) -> String {
         use nym_credentials_interface::Base58;
 
-        self.blind_serial_number_in_g1subgroup().to_bs58()
+        self.blind_serial_number().to_bs58()
     }
 
     pub fn typ(&self) -> CredentialType {
@@ -196,26 +197,12 @@ impl IssuanceBandwidthCredential {
         }
     }
 
-    pub async fn obtain_partial_credential(
+    pub fn unblind_signature(
         &self,
-        client: &nym_validator_client::client::NymApiClient,
         validator_vk: &VerificationKey,
-        signing_data: impl Into<Option<CredentialSigningData>>,
+        signing_data: &CredentialSigningData,
+        blinded_signature: BlindedSignature,
     ) -> Result<Signature, Error> {
-        // if we provided signing data, do use them, otherwise generate fresh data
-        let signing_data = signing_data
-            .into()
-            .unwrap_or_else(|| self.prepare_for_signing());
-
-        let blinded_signature = match &self.variant_data {
-            BandwidthCredentialIssuanceDataVariant::FreePass(_freepass) => unimplemented!(),
-            BandwidthCredentialIssuanceDataVariant::Voucher(voucher) => {
-                // TODO: the request can be re-used between different apis
-                let request = voucher.create_blind_sign_request_body(&signing_data);
-                voucher.obtain_blinded_credential(client, &request).await?
-            }
-        };
-
         let public_attributes = self.get_public_attributes();
         let private_attributes = self.get_private_attributes();
 
@@ -232,6 +219,52 @@ impl IssuanceBandwidthCredential {
         Ok(unblinded_signature)
     }
 
+    pub async fn obtain_partial_freepass_credential(
+        &self,
+        client: &nym_validator_client::client::NymApiClient,
+        account_data: &AccountData,
+        validator_vk: &VerificationKey,
+        signing_data: impl Into<Option<CredentialSigningData>>,
+    ) -> Result<Signature, Error> {
+        // if we provided signing data, do use them, otherwise generate fresh data
+        let signing_data = signing_data
+            .into()
+            .unwrap_or_else(|| self.prepare_for_signing());
+
+        let blinded_signature = match &self.variant_data {
+            BandwidthCredentialIssuanceDataVariant::FreePass(freepass) => {
+                freepass
+                    .request_blinded_credential(&signing_data, account_data, client)
+                    .await?
+            }
+            _ => return Err(Error::NotAFreePass),
+        };
+        self.unblind_signature(validator_vk, &signing_data, blinded_signature)
+    }
+
+    // ideally this would have been generic over credential type, but we really don't need secp256k1 keys for bandwidth vouchers
+    pub async fn obtain_partial_bandwidth_voucher_credential(
+        &self,
+        client: &nym_validator_client::client::NymApiClient,
+        validator_vk: &VerificationKey,
+        signing_data: impl Into<Option<CredentialSigningData>>,
+    ) -> Result<Signature, Error> {
+        // if we provided signing data, do use them, otherwise generate fresh data
+        let signing_data = signing_data
+            .into()
+            .unwrap_or_else(|| self.prepare_for_signing());
+
+        let blinded_signature = match &self.variant_data {
+            BandwidthCredentialIssuanceDataVariant::Voucher(voucher) => {
+                // TODO: the request can be re-used between different apis
+                let request = voucher.create_blind_sign_request_body(&signing_data);
+                voucher.obtain_blinded_credential(client, &request).await?
+            }
+            _ => return Err(Error::NotABandwdithVoucher),
+        };
+        self.unblind_signature(validator_vk, &signing_data, blinded_signature)
+    }
+
     pub fn aggregate_signature_shares(
         &self,
         verification_key: &VerificationKey,
@@ -254,13 +287,15 @@ impl IssuanceBandwidthCredential {
     pub fn into_issued_credential(
         self,
         aggregate_signature: Signature,
+        epoch_id: EpochId,
     ) -> IssuedBandwidthCredential {
-        self.to_issued_credential(aggregate_signature)
+        self.to_issued_credential(aggregate_signature, epoch_id)
     }
 
     pub fn to_issued_credential(
         &self,
         aggregate_signature: Signature,
+        epoch_id: EpochId,
     ) -> IssuedBandwidthCredential {
         IssuedBandwidthCredential::new(
             self.serial_number,
@@ -268,6 +303,7 @@ impl IssuanceBandwidthCredential {
             aggregate_signature,
             (&self.variant_data).into(),
             self.type_prehashed,
+            epoch_id,
         )
     }
 
@@ -279,9 +315,12 @@ impl IssuanceBandwidthCredential {
     }
 
     // TODO: is that actually needed?
+    // idea: make it consistent with the issued credential and its vX serde
     pub fn try_from_recovered_bytes(bytes: &[u8]) -> Result<Self, Error> {
         use bincode::Options;
-        Ok(make_recovery_bincode_serializer().deserialize(bytes)?)
+        make_recovery_bincode_serializer()
+            .deserialize(bytes)
+            .map_err(|source| Error::RecoveryCredentialDeserializationFailure { source })
     }
 }
 
@@ -291,3 +330,18 @@ fn make_recovery_bincode_serializer() -> impl bincode::Options {
         .with_big_endian()
         .with_varint_encoding()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn assert_zeroize_on_drop<T: ZeroizeOnDrop>() {}
+
+    fn assert_zeroize<T: Zeroize>() {}
+
+    #[test]
+    fn credential_is_zeroized() {
+        assert_zeroize::<IssuanceBandwidthCredential>();
+        assert_zeroize_on_drop::<IssuanceBandwidthCredential>();
+    }
+}

common/credentials/src/coconut/bandwidth/issued.rs

@@ -14,12 +14,13 @@ use nym_credentials_interface::prove_bandwidth_credential;
 use nym_credentials_interface::{
     Parameters, PrivateAttribute, PublicAttribute, Signature, VerificationKey,
 };
+use nym_validator_client::nym_api::EpochId;
 use serde::{Deserialize, Serialize};
 use zeroize::{Zeroize, ZeroizeOnDrop};
 
 pub const CURRENT_SERIALIZATION_REVISION: u8 = 1;
 
-#[derive(Zeroize, Serialize, Deserialize)]
+#[derive(Debug, Zeroize, Serialize, Deserialize)]
 pub enum BandwidthCredentialIssuedDataVariant {
     Voucher(BandwidthVoucherIssuedData),
     FreePass(FreePassIssuedData),
@@ -91,6 +92,9 @@ pub struct IssuedBandwidthCredential {
     /// type of the bandwdith credential hashed onto a scalar
     #[serde(with = "scalar_serde_helper")]
     type_prehashed: PublicAttribute,
+
+    /// Specifies the (DKG) epoch id when this credential has been issued
+    epoch_id: EpochId,
 }
 
 impl IssuedBandwidthCredential {
@@ -100,6 +104,7 @@ impl IssuedBandwidthCredential {
         signature: Signature,
         variant_data: BandwidthCredentialIssuedDataVariant,
         type_prehashed: PublicAttribute,
+        epoch_id: EpochId,
     ) -> Self {
         IssuedBandwidthCredential {
             serial_number,
@@ -107,9 +112,27 @@ impl IssuedBandwidthCredential {
             signature,
             variant_data,
             type_prehashed,
+            epoch_id,
         }
     }
 
+    pub fn try_unpack(bytes: &[u8], revision: impl Into<Option<u8>>) -> Result<Self, Error> {
+        let revision = revision.into().unwrap_or(CURRENT_SERIALIZATION_REVISION);
+
+        match revision {
+            1 => Self::unpack_v1(bytes),
+            _ => Err(Error::UnknownSerializationRevision { revision }),
+        }
+    }
+
+    pub fn epoch_id(&self) -> EpochId {
+        self.epoch_id
+    }
+
+    pub fn variant_data(&self) -> &BandwidthCredentialIssuedDataVariant {
+        &self.variant_data
+    }
+
     pub fn current_serialization_revision(&self) -> u8 {
         CURRENT_SERIALIZATION_REVISION
     }
@@ -124,7 +147,12 @@ impl IssuedBandwidthCredential {
     /// Unpack (deserialize) the credential data from the given bytes using v1 serializer.
     pub fn unpack_v1(bytes: &[u8]) -> Result<Self, Error> {
         use bincode::Options;
-        Ok(make_storable_bincode_serializer().deserialize(bytes)?)
+        make_storable_bincode_serializer()
+            .deserialize(bytes)
+            .map_err(|source| Error::SerializationFailure {
+                source,
+                revision: 1,
+            })
     }
 
     pub fn randomise_signature(&mut self) {
@@ -166,6 +194,7 @@ impl IssuedBandwidthCredential {
             verify_credential_request,
             public_attributes_plain: self.get_plain_public_attributes(),
             typ: self.typ(),
+            epoch_id: self.epoch_id,
         })
     }
 }
@@ -176,3 +205,18 @@ fn make_storable_bincode_serializer() -> impl bincode::Options {
         .with_big_endian()
         .with_varint_encoding()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn assert_zeroize_on_drop<T: ZeroizeOnDrop>() {}
+
+    fn assert_zeroize<T: Zeroize>() {}
+
+    #[test]
+    fn credential_is_zeroized() {
+        assert_zeroize::<IssuedBandwidthCredential>();
+        assert_zeroize_on_drop::<IssuedBandwidthCredential>();
+    }
+}

common/credentials/src/coconut/bandwidth/voucher.rs

@@ -13,7 +13,7 @@ use nym_validator_client::nyxd::{Coin, Hash};
 use serde::{Deserialize, Serialize};
 use zeroize::{Zeroize, ZeroizeOnDrop};
 
-#[derive(Zeroize, ZeroizeOnDrop, Serialize, Deserialize)]
+#[derive(Debug, Zeroize, ZeroizeOnDrop, Serialize, Deserialize)]
 pub struct BandwidthVoucherIssuedData {
     /// the plain value (e.g., bandwidth) encoded in this voucher
     // note: for legacy reasons we're only using the value of the coin and ignoring the denom
@@ -30,6 +30,10 @@ impl<'a> From<&'a BandwidthVoucherIssuanceData> for BandwidthVoucherIssuedData {
 }
 
 impl BandwidthVoucherIssuedData {
+    pub fn value(&self) -> &Coin {
+        &self.value
+    }
+
     pub fn value_plain(&self) -> String {
         self.value.amount.to_string()
     }

common/credentials/src/coconut/utils.rs

@@ -9,7 +9,7 @@ use nym_credentials_interface::{
 };
 use nym_validator_client::client::CoconutApiClient;
 
-pub async fn obtain_aggregate_verification_key(
+pub fn obtain_aggregate_verification_key(
     api_clients: &[CoconutApiClient],
 ) -> Result<VerificationKey, Error> {
     if api_clients.is_empty() {
@@ -37,7 +37,7 @@ pub async fn obtain_aggregate_signature(
         return Err(Error::NoValidatorsAvailable);
     }
     let mut shares = Vec::with_capacity(coconut_api_clients.len());
-    let verification_key = obtain_aggregate_verification_key(coconut_api_clients).await?;
+    let verification_key = obtain_aggregate_verification_key(coconut_api_clients)?;
 
     let request = voucher.prepare_for_signing();
 
@@ -48,7 +48,7 @@ pub async fn obtain_aggregate_signature(
         );
 
         match voucher
-            .obtain_partial_credential(
+            .obtain_partial_bandwidth_voucher_credential(
                 &coconut_api_client.api_client,
                 &coconut_api_client.verification_key,
                 Some(request.clone()),

common/credentials/src/error.rs

@@ -5,6 +5,7 @@ use nym_credentials_interface::CoconutError;
 use nym_crypto::asymmetric::encryption::KeyRecoveryError;
 use nym_validator_client::ValidatorClientError;
 
+use crate::coconut::bandwidth::issued::CURRENT_SERIALIZATION_REVISION;
 use thiserror::Error;
 
 #[derive(Debug, Error)]
@@ -12,8 +13,18 @@ pub enum Error {
     #[error("IO error")]
     IOError(#[from] std::io::Error),
 
-    #[error("failed to (de)serialize credential structure: {0}")]
-    SerializationFailure(#[from] bincode::Error),
+    #[error("failed to deserialize a recovery credential: {source}")]
+    RecoveryCredentialDeserializationFailure { source: bincode::Error },
+
+    #[error("failed to (de)serialize provided credential using revision {revision}: {source}")]
+    SerializationFailure {
+        #[source]
+        source: bincode::Error,
+        revision: u8,
+    },
+
+    #[error("unknown credential serializatio revision {revision}. the current (and max supported) version is {CURRENT_SERIALIZATION_REVISION}")]
+    UnknownSerializationRevision { revision: u8 },
 
     #[error("The detailed description is yet to be determined")]
     BandwidthCredentialError,
@@ -44,4 +55,13 @@ pub enum Error {
 
     #[error("Could not deserialize bandwidth voucher - {0}")]
     BandwidthVoucherDeserializationError(String),
+
+    #[error("the provided issuance data wasn't prepared for a bandwidth voucher")]
+    NotABandwdithVoucher,
+
+    #[error("the provided issuance data wasn't prepared for a free pass")]
+    NotAFreePass,
+
+    #[error("failed to create a secp256k1 signature")]
+    Secp256k1SignFailure,
 }

common/credentials/src/lib.rs

@@ -9,3 +9,4 @@ pub use coconut::bandwidth::{
     IssuedBandwidthCredential,
 };
 pub use coconut::utils::{obtain_aggregate_signature, obtain_aggregate_verification_key};
+pub use error::Error;

common/crypto/Cargo.toml

@@ -9,7 +9,7 @@ repository = { workspace = true }
 
 [dependencies]
 aes = { version = "0.8.1", optional = true }
-bs58 = "0.4.0"
+bs58 = { workspace = true }
 blake3 = { version = "1.3.1", features = ["traits-preview"], optional = true }
 ctr = { version = "0.9.1", optional = true }
 digest = { version = "0.10.3", optional = true }

common/dkg/Cargo.toml

@@ -14,7 +14,7 @@ bitvec = "1.0.0"
 # as we need to be able to serialize Gt so that we could create the lookup table for baby-step-giant-step algorithm
 bls12_381 = { workspace = true, default-features = false, features = ["alloc", "pairings", "experimental", "zeroize"] }
 nym-contracts-common = { path = "../cosmwasm-smart-contracts/contracts-common", optional = true }
-bs58 = "0.4"
+bs58 = { workspace = true }
 
 
 lazy_static = "1.4.0"

common/ip-packet-requests/Cargo.toml

@@ -11,6 +11,7 @@ license.workspace = true
 [dependencies]
 bincode = "1.3.3"
 bytes = "1.5.0"
+nym-bin-common = { path = "../bin-common" }
 nym-sphinx = { path = "../nymsphinx" }
 rand = "0.8.5"
 serde = { workspace = true, features = ["derive"] }

common/ip-packet-requests/src/lib.rs

@@ -1,8 +1,33 @@
+use serde::{Deserialize, Serialize};
+use std::fmt::{Display, Formatter};
+use std::net::{Ipv4Addr, Ipv6Addr};
+
 pub mod codec;
 pub mod request;
 pub mod response;
 
-pub const CURRENT_VERSION: u8 = 2;
+// version 3: initial version
+// version 4: IPv6 support
+// version 5: Add severity level to info response
+pub const CURRENT_VERSION: u8 = 5;
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub struct IpPair {
+    pub ipv4: Ipv4Addr,
+    pub ipv6: Ipv6Addr,
+}
+
+impl IpPair {
+    pub fn new(ipv4: Ipv4Addr, ipv6: Ipv6Addr) -> Self {
+        IpPair { ipv4, ipv6 }
+    }
+}
+
+impl Display for IpPair {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        writeln!(f, "IPv4: {}, IPV6: {}", self.ipv4, self.ipv6)
+    }
+}
 
 fn make_bincode_serializer() -> impl bincode::Options {
     use bincode::Options;

common/ip-packet-requests/src/request.rs

@@ -1,9 +1,7 @@
-use std::net::IpAddr;
-
 use nym_sphinx::addressing::clients::Recipient;
 use serde::{Deserialize, Serialize};
 
-use crate::{make_bincode_serializer, CURRENT_VERSION};
+use crate::{make_bincode_serializer, IpPair, CURRENT_VERSION};
 
 fn generate_random() -> u64 {
     use rand::RngCore;
@@ -19,10 +17,11 @@ pub struct IpPacketRequest {
 
 impl IpPacketRequest {
     pub fn new_static_connect_request(
-        ip: IpAddr,
+        ips: IpPair,
         reply_to: Recipient,
         reply_to_hops: Option<u8>,
         reply_to_avg_mix_delays: Option<f64>,
+        buffer_timeout: Option<u64>,
     ) -> (Self, u64) {
         let request_id = generate_random();
         (
@@ -30,10 +29,11 @@ impl IpPacketRequest {
                 version: CURRENT_VERSION,
                 data: IpPacketRequestData::StaticConnect(StaticConnectRequest {
                     request_id,
-                    ip,
+                    ips,
                     reply_to,
                     reply_to_hops,
                     reply_to_avg_mix_delays,
+                    buffer_timeout,
                 }),
             },
             request_id,
@@ -44,6 +44,7 @@ impl IpPacketRequest {
         reply_to: Recipient,
         reply_to_hops: Option<u8>,
         reply_to_avg_mix_delays: Option<f64>,
+        buffer_timeout: Option<u64>,
     ) -> (Self, u64) {
         let request_id = generate_random();
         (
@@ -54,6 +55,7 @@ impl IpPacketRequest {
                     reply_to,
                     reply_to_hops,
                     reply_to_avg_mix_delays,
+                    buffer_timeout,
                 }),
             },
             request_id,
@@ -74,10 +76,10 @@ impl IpPacketRequest {
         )
     }
 
-    pub fn new_ip_packet(ip_packet: bytes::Bytes) -> Self {
+    pub fn new_data_request(ip_packets: bytes::Bytes) -> Self {
         Self {
             version: CURRENT_VERSION,
-            data: IpPacketRequestData::Data(DataRequest { ip_packet }),
+            data: IpPacketRequestData::Data(DataRequest { ip_packets }),
         }
     }
 
@@ -87,6 +89,8 @@ impl IpPacketRequest {
             IpPacketRequestData::DynamicConnect(request) => Some(request.request_id),
             IpPacketRequestData::Disconnect(request) => Some(request.request_id),
             IpPacketRequestData::Data(_) => None,
+            IpPacketRequestData::Ping(request) => Some(request.request_id),
+            IpPacketRequestData::Health(request) => Some(request.request_id),
         }
     }
 
@@ -96,6 +100,8 @@ impl IpPacketRequest {
             IpPacketRequestData::DynamicConnect(request) => Some(&request.reply_to),
             IpPacketRequestData::Disconnect(request) => Some(&request.reply_to),
             IpPacketRequestData::Data(_) => None,
+            IpPacketRequestData::Ping(request) => Some(&request.reply_to),
+            IpPacketRequestData::Health(request) => Some(&request.reply_to),
         }
     }
 
@@ -119,35 +125,58 @@ pub enum IpPacketRequestData {
     DynamicConnect(DynamicConnectRequest),
     Disconnect(DisconnectRequest),
     Data(DataRequest),
+    Ping(PingRequest),
+    Health(HealthRequest),
 }
 
+// A static connect request is when the client provides the internal IP address it will use on the
+// ip packet router.
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 pub struct StaticConnectRequest {
     pub request_id: u64,
-    pub ip: IpAddr,
+
+    pub ips: IpPair,
+
     // The nym-address the response should be sent back to
     pub reply_to: Recipient,
+
     // The number of mix node hops that responses should take, in addition to the entry and exit
     // node. Zero means only client -> entry -> exit -> client.
     pub reply_to_hops: Option<u8>,
+
     // The average delay at each mix node, in milliseconds. Currently this is not supported by the
     // ip packet router.
     pub reply_to_avg_mix_delays: Option<f64>,
+
+    // The maximum time in milliseconds the IPR should wait when filling up a mix packet
+    // with ip packets.
+    pub buffer_timeout: Option<u64>,
 }
 
+// A dynamic connect request is when the client does not provide the internal IP address it will use
+// on the ip packet router, and instead requests one to be assigned to it.
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 pub struct DynamicConnectRequest {
     pub request_id: u64,
+
     // The nym-address the response should be sent back to
     pub reply_to: Recipient,
+
     // The number of mix node hops that responses should take, in addition to the entry and exit
     // node. Zero means only client -> entry -> exit -> client.
     pub reply_to_hops: Option<u8>,
+
     // The average delay at each mix node, in milliseconds. Currently this is not supported by the
     // ip packet router.
     pub reply_to_avg_mix_delays: Option<f64>,
+
+    // The maximum time in milliseconds the IPR should wait when filling up a mix packet
+    // with ip packets.
+    pub buffer_timeout: Option<u64>,
 }
 
+// A disconnect request is when the client wants to disconnect from the ip packet router and free
+// up the allocated IP address.
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 pub struct DisconnectRequest {
     pub request_id: u64,
@@ -155,14 +184,32 @@ pub struct DisconnectRequest {
     pub reply_to: Recipient,
 }
 
+// A data request is when the client wants to send an IP packet to a destination.
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 pub struct DataRequest {
-    pub ip_packet: bytes::Bytes,
+    pub ip_packets: bytes::Bytes,
+}
+
+// A ping request is when the client wants to check if the ip packet router is still alive.
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct PingRequest {
+    pub request_id: u64,
+    // The nym-address the response should be sent back to
+    pub reply_to: Recipient,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub struct HealthRequest {
+    pub request_id: u64,
+    // The nym-address the response should be sent back to
+    pub reply_to: Recipient,
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::net::{Ipv4Addr, Ipv6Addr};
+    use std::str::FromStr;
 
     #[test]
     fn check_size_of_request() {
@@ -171,14 +218,15 @@ mod tests {
             data: IpPacketRequestData::StaticConnect(
                 StaticConnectRequest {
                     request_id: 123,
-                    ip: IpAddr::from([10, 0, 0, 1]),
+                    ips: IpPair::new(Ipv4Addr::from_str("10.0.0.1").unwrap(), Ipv6Addr::from_str("2001:db8:a160::1").unwrap()),
                     reply_to: Recipient::try_from_base58_string("D1rrpsysCGCYXy9saP8y3kmNpGtJZUXN9SvFoUcqAsM9.9Ssso1ea5NfkbMASdiseDSjTN1fSWda5SgEVjdSN4CvV@GJqd3ZxpXWSNxTfx7B1pPtswpetH4LnJdFeLeuY5KUuN").unwrap(),
                     reply_to_hops: None,
                     reply_to_avg_mix_delays: None,
+                    buffer_timeout: None,
                 },
-            )
+            ),
         };
-        assert_eq!(connect.to_bytes().unwrap().len(), 107);
+        assert_eq!(connect.to_bytes().unwrap().len(), 123);
     }
 
     #[test]
@@ -186,7 +234,7 @@ mod tests {
         let data = IpPacketRequest {
             version: 4,
             data: IpPacketRequestData::Data(DataRequest {
-                ip_packet: bytes::Bytes::from(vec![1u8; 32]),
+                ip_packets: bytes::Bytes::from(vec![1u8; 32]),
             }),
         };
         assert_eq!(data.to_bytes().unwrap().len(), 35);
@@ -197,7 +245,7 @@ mod tests {
         let data = IpPacketRequest {
             version: 4,
             data: IpPacketRequestData::Data(DataRequest {
-                ip_packet: bytes::Bytes::from(vec![1, 2, 4, 2, 5]),
+                ip_packets: bytes::Bytes::from(vec![1, 2, 4, 2, 5]),
             }),
         };
 
@@ -214,7 +262,7 @@ mod tests {
         assert_eq!(
             deserialized.data,
             IpPacketRequestData::Data(DataRequest {
-                ip_packet: bytes::Bytes::from(vec![1, 2, 4, 2, 5]),
+                ip_packets: bytes::Bytes::from(vec![1, 2, 4, 2, 5]),
             })
         );
     }

common/ip-packet-requests/src/response.rs

@@ -1,9 +1,7 @@
-use std::net::IpAddr;
-
 use nym_sphinx::addressing::clients::Recipient;
 use serde::{Deserialize, Serialize};
 
-use crate::{make_bincode_serializer, CURRENT_VERSION};
+use crate::{make_bincode_serializer, IpPair, CURRENT_VERSION};
 
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct IpPacketResponse {
@@ -38,13 +36,13 @@ impl IpPacketResponse {
         }
     }
 
-    pub fn new_dynamic_connect_success(request_id: u64, reply_to: Recipient, ip: IpAddr) -> Self {
+    pub fn new_dynamic_connect_success(request_id: u64, reply_to: Recipient, ips: IpPair) -> Self {
         Self {
             version: CURRENT_VERSION,
             data: IpPacketResponseData::DynamicConnect(DynamicConnectResponse {
                 request_id,
                 reply_to,
-                reply: DynamicConnectResponseReply::Success(DynamicConnectSuccess { ip }),
+                reply: DynamicConnectResponseReply::Success(DynamicConnectSuccess { ips }),
             }),
         }
     }
@@ -64,6 +62,45 @@ impl IpPacketResponse {
         }
     }
 
+    pub fn new_disconnect_success(request_id: u64, reply_to: Recipient) -> Self {
+        Self {
+            version: CURRENT_VERSION,
+            data: IpPacketResponseData::Disconnect(DisconnectResponse {
+                request_id,
+                reply_to,
+                reply: DisconnectResponseReply::Success,
+            }),
+        }
+    }
+
+    pub fn new_disconnect_failure(
+        request_id: u64,
+        reply_to: Recipient,
+        reason: DisconnectFailureReason,
+    ) -> Self {
+        Self {
+            version: CURRENT_VERSION,
+            data: IpPacketResponseData::Disconnect(DisconnectResponse {
+                request_id,
+                reply_to,
+                reply: DisconnectResponseReply::Failure(reason),
+            }),
+        }
+    }
+
+    pub fn new_unrequested_disconnect(
+        reply_to: Recipient,
+        reason: UnrequestedDisconnectReason,
+    ) -> Self {
+        Self {
+            version: CURRENT_VERSION,
+            data: IpPacketResponseData::UnrequestedDisconnect(UnrequestedDisconnect {
+                reply_to,
+                reason,
+            }),
+        }
+    }
+
     pub fn new_ip_packet(ip_packet: bytes::Bytes) -> Self {
         Self {
             version: CURRENT_VERSION,
@@ -79,24 +116,30 @@ impl IpPacketResponse {
     ) -> Self {
         Self {
             version: CURRENT_VERSION,
-            data: IpPacketResponseData::Error(ErrorResponse {
+            data: IpPacketResponseData::Info(InfoResponse {
                 request_id,
                 reply_to,
-                reply: ErrorResponseReply::VersionMismatch {
+                reply: InfoResponseReply::VersionMismatch {
                     request_version,
                     response_version: our_version,
                 },
+                level: InfoLevel::Error,
             }),
         }
     }
 
-    pub fn new_data_error_response(reply_to: Recipient, reply: ErrorResponseReply) -> Self {
+    pub fn new_data_info_response(
+        reply_to: Recipient,
+        reply: InfoResponseReply,
+        level: InfoLevel,
+    ) -> Self {
         Self {
             version: CURRENT_VERSION,
-            data: IpPacketResponseData::Error(ErrorResponse {
+            data: IpPacketResponseData::Info(InfoResponse {
                 request_id: 0,
                 reply_to,
                 reply,
+                level,
             }),
         }
     }
@@ -106,8 +149,11 @@ impl IpPacketResponse {
             IpPacketResponseData::StaticConnect(response) => Some(response.request_id),
             IpPacketResponseData::DynamicConnect(response) => Some(response.request_id),
             IpPacketResponseData::Disconnect(response) => Some(response.request_id),
+            IpPacketResponseData::UnrequestedDisconnect(_) => None,
             IpPacketResponseData::Data(_) => None,
-            IpPacketResponseData::Error(response) => Some(response.request_id),
+            IpPacketResponseData::Pong(response) => Some(response.request_id),
+            IpPacketResponseData::Health(response) => Some(response.request_id),
+            IpPacketResponseData::Info(response) => Some(response.request_id),
         }
     }
 
@@ -116,8 +162,11 @@ impl IpPacketResponse {
             IpPacketResponseData::StaticConnect(response) => Some(&response.reply_to),
             IpPacketResponseData::DynamicConnect(response) => Some(&response.reply_to),
             IpPacketResponseData::Disconnect(response) => Some(&response.reply_to),
+            IpPacketResponseData::UnrequestedDisconnect(response) => Some(&response.reply_to),
             IpPacketResponseData::Data(_) => None,
-            IpPacketResponseData::Error(response) => Some(&response.reply_to),
+            IpPacketResponseData::Pong(response) => Some(&response.reply_to),
+            IpPacketResponseData::Health(response) => Some(&response.reply_to),
+            IpPacketResponseData::Info(response) => Some(&response.reply_to),
         }
     }
 
@@ -137,11 +186,29 @@ impl IpPacketResponse {
 #[allow(clippy::large_enum_variant)]
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub enum IpPacketResponseData {
+    // Response for a static connect request
     StaticConnect(StaticConnectResponse),
+
+    // Response for a dynamic connect request
     DynamicConnect(DynamicConnectResponse),
+
+    // Response for a disconnect initiqated by the client
     Disconnect(DisconnectResponse),
+
+    // Message from the server that the client got disconnected without the client initiating it
+    UnrequestedDisconnect(UnrequestedDisconnect),
+
+    // Response to a data request
     Data(DataResponse),
-    Error(ErrorResponse),
+
+    // Response to ping request
+    Pong(PongResponse),
+
+    // Response for a health request
+    Health(HealthResponse),
+
+    // Info response. This can be anything from informative messages to errors
+    Info(InfoResponse),
 }
 
 #[derive(Clone, Debug, Serialize, Deserialize)]
@@ -200,7 +267,7 @@ impl DynamicConnectResponseReply {
 
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct DynamicConnectSuccess {
-    pub ip: IpAddr,
+    pub ips: IpPair,
 }
 
 #[derive(Clone, Debug, Serialize, Deserialize, thiserror::Error)]
@@ -234,20 +301,58 @@ pub enum DisconnectFailureReason {
     Other(String),
 }
 
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct UnrequestedDisconnect {
+    pub reply_to: Recipient,
+    pub reason: UnrequestedDisconnectReason,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, thiserror::Error)]
+pub enum UnrequestedDisconnectReason {
+    #[error("client mixnet traffic timeout")]
+    ClientMixnetTrafficTimeout,
+    #[error("client tun traffic timeout")]
+    ClientTunTrafficTimeout,
+    #[error("{0}")]
+    Other(String),
+}
+
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct DataResponse {
     pub ip_packet: bytes::Bytes,
 }
 
 #[derive(Clone, Debug, Serialize, Deserialize)]
-pub struct ErrorResponse {
+pub struct PongResponse {
     pub request_id: u64,
     pub reply_to: Recipient,
-    pub reply: ErrorResponseReply,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct HealthResponse {
+    pub request_id: u64,
+    pub reply_to: Recipient,
+    pub reply: HealthResponseReply,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct HealthResponseReply {
+    // Return the binary build information of the IPR
+    pub build_info: nym_bin_common::build_information::BinaryBuildInformationOwned,
+    // Return if the IPR has performed a successful routing test.
+    pub routable: Option<bool>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct InfoResponse {
+    pub request_id: u64,
+    pub reply_to: Recipient,
+    pub reply: InfoResponseReply,
+    pub level: InfoLevel,
 }
 
 #[derive(Clone, Debug, Serialize, Deserialize, thiserror::Error)]
-pub enum ErrorResponseReply {
+pub enum InfoResponseReply {
     #[error("{msg}")]
     Generic { msg: String },
     #[error(
@@ -260,3 +365,10 @@ pub enum ErrorResponseReply {
     #[error("destination failed exit policy filter check: {dst}")]
     ExitPolicyFilterCheckFailed { dst: String },
 }
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum InfoLevel {
+    Info,
+    Warn,
+    Error,
+}

common/nym-id/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "nym-id"
+version = "0.1.0"
+authors.workspace = true
+repository.workspace = true
+homepage.workspace = true
+documentation.workspace = true
+edition.workspace = true
+license.workspace = true
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+thiserror.workspace = true
+time.workspace = true
+tracing.workspace = true
+zeroize.workspace = true
+
+nym-credential-storage = { path = "../credential-storage" }
+nym-credentials = { path = "../credentials" }

common/nym-id/src/error.rs

@@ -0,0 +1,20 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use std::error::Error;
+use thiserror::Error;
+use time::OffsetDateTime;
+
+#[derive(Debug, Error)]
+pub enum NymIdError {
+    #[error("failed to deserialize provided credential: {source}")]
+    CredentialDeserializationFailure { source: nym_credentials::Error },
+
+    #[error("attempted to import an expired credential (it expired on {expiration})")]
+    ExpiredCredentialImport { expiration: OffsetDateTime },
+
+    #[error("failed to store credential in the provided store: {source}")]
+    StorageError {
+        source: Box<dyn Error + Send + Sync>,
+    },
+}

common/nym-id/src/import_credential.rs

@@ -0,0 +1,71 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::NymIdError;
+use nym_credential_storage::models::StorableIssuedCredential;
+use nym_credential_storage::storage::Storage;
+use nym_credentials::coconut::bandwidth::issued::BandwidthCredentialIssuedDataVariant;
+use nym_credentials::IssuedBandwidthCredential;
+use tracing::{debug, warn};
+use zeroize::Zeroizing;
+
+pub async fn import_credential<S>(
+    credentials_store: S,
+    raw_credential: Vec<u8>,
+    credential_version: impl Into<Option<u8>>,
+) -> Result<(), NymIdError>
+where
+    S: Storage,
+    <S as Storage>::StorageError: Send + Sync + 'static,
+{
+    let raw_credential = Zeroizing::new(raw_credential);
+
+    // note: the type itself implements ZeroizeOnDrop
+    let credential = IssuedBandwidthCredential::try_unpack(&raw_credential, credential_version)
+        .map_err(|source| NymIdError::CredentialDeserializationFailure { source })?;
+
+    debug!(
+        "attempting to import credential of type {}",
+        credential.typ()
+    );
+
+    match credential.variant_data() {
+        BandwidthCredentialIssuedDataVariant::Voucher(voucher_info) => {
+            debug!("with value of {}", voucher_info.value())
+        }
+        BandwidthCredentialIssuedDataVariant::FreePass(freepass_info) => {
+            debug!("with expiry at {}", freepass_info.expiry_date());
+            if freepass_info.expired() {
+                warn!("the free pass has already expired!");
+
+                // technically we can import it, but the gateway will just reject it so what's the point
+                return Err(NymIdError::ExpiredCredentialImport {
+                    expiration: freepass_info.expiry_date(),
+                });
+            }
+        }
+    }
+
+    // SAFETY:
+    // for the epoch to run over u32::MAX, we'd have to advance it for few centuries every block...
+    // the alternative is a very particularly malformed serialized data, but at that point blowing up is the right call
+    // because we can't rely on it anyway
+    #[allow(clippy::expect_used)]
+    let storable = StorableIssuedCredential {
+        serialization_revision: credential.current_serialization_revision(),
+        credential_data: &raw_credential,
+        credential_type: credential.typ().to_string(),
+        epoch_id: credential
+            .epoch_id()
+            .try_into()
+            .expect("our epoch is has run over u32::MAX!"),
+    };
+
+    credentials_store
+        .insert_issued_credential(storable)
+        .await
+        .map_err(|source| NymIdError::StorageError {
+            source: Box::new(source),
+        })?;
+    Ok(())
+}

common/nym-id/src/lib.rs

@@ -0,0 +1,11 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+#![warn(clippy::expect_used)]
+#![warn(clippy::unwrap_used)]
+
+pub mod error;
+pub mod import_credential;
+
+pub use error::NymIdError;
+pub use import_credential::import_credential;

common/nymcoconut/Cargo.toml

@@ -15,7 +15,7 @@ rand = "0.8"
 thiserror = { workspace = true }
 serde = { workspace = true }
 serde_derive = "1.0"
-bs58 = "0.4.0"
+bs58 = { workspace = true }
 sha2 = "0.9"
 zeroize = { workspace = true, optional = true }
 

common/nymcoconut/src/lib.rs

@@ -24,6 +24,7 @@ pub use scheme::setup::Parameters;
 pub use scheme::verification::check_vk_pairing;
 pub use scheme::verification::prove_bandwidth_credential;
 pub use scheme::verification::verify_credential;
+pub use scheme::verification::BlindedSerialNumber;
 pub use scheme::verification::VerifyCredentialRequest;
 pub use scheme::BlindedSignature;
 pub use scheme::Signature;

common/nymcoconut/src/scheme/double_use.rs

@@ -1,17 +1,46 @@
-// Copyright 2022 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2022-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
-use bls12_381::G2Projective;
-use group::Curve;
-use std::convert::TryFrom;
-use std::convert::TryInto;
-
 use crate::error::{CoconutError, Result};
 use crate::traits::{Base58, Bytable};
 use crate::utils::try_deserialize_g2_projective;
+use bls12_381::{G2Affine, G2Projective};
+use group::Curve;
+use std::convert::TryFrom;
+use std::convert::TryInto;
+use std::fmt::{Debug, Formatter};
+use std::ops::Deref;
 
-pub struct BlindedSerialNumber {
-    pub(crate) inner: G2Projective,
+#[derive(PartialEq, Eq, Clone, Copy)]
+pub struct BlindedSerialNumber(G2Projective);
+
+// use custom Debug implementation to show base58 encoding (rather than raw curve elements)
+impl Debug for BlindedSerialNumber {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        f.debug_tuple("BlindedSerialNumber")
+            .field(&self.to_bs58())
+            .finish()
+    }
+}
+
+impl From<G2Projective> for BlindedSerialNumber {
+    fn from(value: G2Projective) -> Self {
+        BlindedSerialNumber(value)
+    }
+}
+
+impl From<G2Affine> for BlindedSerialNumber {
+    fn from(value: G2Affine) -> Self {
+        BlindedSerialNumber(value.into())
+    }
+}
+
+impl Deref for BlindedSerialNumber {
+    type Target = G2Projective;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
 }
 
 impl TryFrom<&[u8]> for BlindedSerialNumber {
@@ -34,13 +63,13 @@ impl TryFrom<&[u8]> for BlindedSerialNumber {
             ),
         )?;
 
-        Ok(BlindedSerialNumber { inner })
+        Ok(BlindedSerialNumber(inner))
     }
 }
 
 impl Bytable for BlindedSerialNumber {
     fn to_byte_vec(&self) -> Vec<u8> {
-        self.inner.to_affine().to_compressed().to_vec()
+        self.0.to_affine().to_compressed().to_vec()
     }
 
     fn try_from_byte_slice(slice: &[u8]) -> Result<Self> {

common/nymcoconut/src/scheme/mod.rs

@@ -248,6 +248,15 @@ pub struct SignatureShare {
     index: SignerIndex,
 }
 
+impl From<(Signature, SignerIndex)> for SignatureShare {
+    fn from(value: (Signature, SignerIndex)) -> Self {
+        SignatureShare {
+            signature: value.0,
+            index: value.1,
+        }
+    }
+}
+
 impl SignatureShare {
     pub fn new(signature: Signature, index: SignerIndex) -> Self {
         SignatureShare { signature, index }

common/nymcoconut/src/scheme/verification.rs

@@ -1,22 +1,21 @@
-// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2021-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
-use core::ops::Neg;
-use std::convert::TryFrom;
-use std::convert::TryInto;
-
-use bls12_381::{multi_miller_loop, G1Affine, G2Prepared, G2Projective, Scalar};
-use group::{Curve, Group};
-
 use crate::error::{CoconutError, Result};
 use crate::proofs::ProofKappaZeta;
-use crate::scheme::double_use::BlindedSerialNumber;
 use crate::scheme::setup::Parameters;
 use crate::scheme::Signature;
 use crate::scheme::VerificationKey;
 use crate::traits::{Base58, Bytable};
 use crate::utils::try_deserialize_g2_projective;
 use crate::Attribute;
+use bls12_381::{multi_miller_loop, G1Affine, G2Prepared, G2Projective, Scalar};
+use core::ops::Neg;
+use group::{Curve, Group};
+use std::convert::TryFrom;
+use std::convert::TryInto;
+
+pub use crate::scheme::double_use::BlindedSerialNumber;
 
 // TODO NAMING: this whole thing
 // Theta
@@ -25,7 +24,7 @@ pub struct VerifyCredentialRequest {
     // blinded_message (kappa)
     pub blinded_message: G2Projective,
     // blinded serial number (zeta)
-    pub blinded_serial_number: G2Projective,
+    pub blinded_serial_number: BlindedSerialNumber,
     // sigma
     pub credential: Signature,
     // pi_v
@@ -53,15 +52,10 @@ impl TryFrom<&[u8]> for VerifyCredentialRequest {
             ),
         )?;
 
-        // safety: we just checked for the length so the unwraps are fine
-        #[allow(clippy::unwrap_used)]
-        let blinded_serial_number_bytes = bytes[96..192].try_into().unwrap();
-        let blinded_serial_number = try_deserialize_g2_projective(
-            &blinded_serial_number_bytes,
-            CoconutError::Deserialization(
-                "failed to deserialize the blinded serial number (zeta)".to_string(),
-            ),
-        )?;
+        let blinded_serial_number_bytes = &bytes[96..192];
+        let blinded_serial_number =
+            BlindedSerialNumber::try_from_byte_slice(blinded_serial_number_bytes)?;
+
         let credential = Signature::try_from(&bytes[192..288])?;
 
         let pi_v = ProofKappaZeta::from_bytes(&bytes[288..])?;
@@ -87,7 +81,7 @@ impl VerifyCredentialRequest {
 
     pub fn has_blinded_serial_number(&self, blinded_serial_number_bs58: &str) -> Result<bool> {
         let blinded_serial_number = BlindedSerialNumber::try_from_bs58(blinded_serial_number_bs58)?;
-        let ret = self.blinded_serial_number.eq(&blinded_serial_number.inner);
+        let ret = self.blinded_serial_number.eq(&blinded_serial_number);
         Ok(ret)
     }
 
@@ -111,11 +105,12 @@ impl VerifyCredentialRequest {
         VerifyCredentialRequest::try_from(bytes)
     }
 
+    pub fn blinded_serial_number(&self) -> BlindedSerialNumber {
+        self.blinded_serial_number
+    }
+
     pub fn blinded_serial_number_bs58(&self) -> String {
-        let blinded_serial_nuumber = BlindedSerialNumber {
-            inner: self.blinded_serial_number,
-        };
-        blinded_serial_nuumber.to_bs58()
+        self.blinded_serial_number.to_bs58()
     }
 }
 
@@ -198,7 +193,7 @@ pub fn prove_bandwidth_credential(
 
     Ok(VerifyCredentialRequest {
         blinded_message,
-        blinded_serial_number,
+        blinded_serial_number: blinded_serial_number.into(),
         credential: signature_prime,
         pi_v,
     })

common/nymnoise/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "nym-noise"
+version = "0.1.0"
+authors = ["Simon Wicky <simon@nymtech.net>"]
+edition = "2021"
+license.workspace = true
+
+[dependencies]
+snow = "0.9.2"
+futures = "0.3"
+tokio = { version = "1.24.1", features = ["net","io-util","time"] }
+tokio-util = { workspace = true, features = ["codec"] }
+pin-project = "1"
+log = "0.4.19"
+sha2 = "0.10.7"
+bytes = "1.0"
+thiserror = "1.0.44"
+semver = "0.11"
+
+# internal
+nym-topology = { path = "../topology"}
+nym-crypto = { path = "../crypto" }

common/nymnoise/src/connection.rs

@@ -0,0 +1,72 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+use std::io;
+
+use pin_project::pin_project;
+use tokio::{
+    io::{AsyncRead, AsyncWrite},
+    net::TcpStream,
+};
+
+use crate::stream::NoiseStream;
+
+#[pin_project(project = ConnectionProj)]
+pub enum Connection {
+    Tcp(#[pin] TcpStream),
+    Noise(#[pin] NoiseStream),
+}
+
+impl Connection {
+    pub fn peer_addr(&self) -> Result<std::net::SocketAddr, io::Error> {
+        match self {
+            Self::Noise(stream) => stream.peer_addr(),
+            Self::Tcp(stream) => stream.peer_addr(),
+        }
+    }
+}
+
+impl AsyncRead for Connection {
+    fn poll_read(
+        self: std::pin::Pin<&mut Self>,
+        cx: &mut std::task::Context<'_>,
+        buf: &mut tokio::io::ReadBuf<'_>,
+    ) -> std::task::Poll<io::Result<()>> {
+        match self.project() {
+            ConnectionProj::Noise(stream) => stream.poll_read(cx, buf),
+            ConnectionProj::Tcp(stream) => stream.poll_read(cx, buf),
+        }
+    }
+}
+
+impl AsyncWrite for Connection {
+    fn poll_write(
+        self: std::pin::Pin<&mut Self>,
+        cx: &mut std::task::Context<'_>,
+        buf: &[u8],
+    ) -> std::task::Poll<Result<usize, io::Error>> {
+        match self.project() {
+            ConnectionProj::Noise(stream) => stream.poll_write(cx, buf),
+            ConnectionProj::Tcp(stream) => stream.poll_write(cx, buf),
+        }
+    }
+    fn poll_flush(
+        self: std::pin::Pin<&mut Self>,
+        cx: &mut std::task::Context<'_>,
+    ) -> std::task::Poll<Result<(), io::Error>> {
+        match self.project() {
+            ConnectionProj::Noise(stream) => stream.poll_flush(cx),
+            ConnectionProj::Tcp(stream) => stream.poll_flush(cx),
+        }
+    }
+
+    fn poll_shutdown(
+        self: std::pin::Pin<&mut Self>,
+        cx: &mut std::task::Context<'_>,
+    ) -> std::task::Poll<Result<(), io::Error>> {
+        match self.project() {
+            ConnectionProj::Noise(stream) => stream.poll_shutdown(cx),
+            ConnectionProj::Tcp(stream) => stream.poll_shutdown(cx),
+        }
+    }
+}

common/nymnoise/src/error.rs

@@ -0,0 +1,43 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+use snow::Error;
+use std::io;
+use std::num::TryFromIntError;
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum NoiseError {
+    #[error("encountered a Noise decryption error")]
+    DecryptionError,
+
+    #[error("encountered a Noise Protocol error - {0}")]
+    ProtocolError(Error),
+
+    #[error("encountered an IO error - {0}")]
+    IoError(#[from] io::Error),
+
+    #[error("Incorrect state")]
+    IncorrectStateError,
+
+    #[error("Handshake timeout")]
+    HandshakeTimeoutError(#[from] tokio::time::error::Elapsed),
+
+    #[error("Handshake did not complete")]
+    HandshakeError,
+
+    #[error(transparent)]
+    IntConversionError(#[from] TryFromIntError),
+
+    #[error("unable to extract public key - {0}")]
+    EncryptionKeyConversionError(#[from] nym_crypto::asymmetric::encryption::KeyRecoveryError),
+}
+
+impl From<Error> for NoiseError {
+    fn from(err: Error) -> Self {
+        match err {
+            Error::Decrypt => NoiseError::DecryptionError,
+            err => NoiseError::ProtocolError(err),
+        }
+    }
+}

common/nymnoise/src/lib.rs

@@ -0,0 +1,148 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+use crate::connection::Connection;
+use crate::error::NoiseError;
+use crate::stream::{NoisePattern, NoiseStream};
+use log::*;
+use nym_crypto::asymmetric::encryption;
+use nym_topology::NymTopology;
+use sha2::{Digest, Sha256};
+use snow::{error::Prerequisite, Builder, Error};
+use tokio::net::TcpStream;
+
+pub mod connection;
+pub mod error;
+pub mod stream;
+
+const NOISE_PSK_PREFIX: &[u8] = b"NYMTECH_NOISE_dQw4w9WgXcQ";
+
+pub async fn upgrade_noise_initiator(
+    conn: TcpStream,
+    pattern: NoisePattern,
+    local_private_key: &encryption::PrivateKey,
+    remote_pub_key: &encryption::PublicKey,
+    epoch: u32,
+) -> Result<Connection, NoiseError> {
+    trace!("Perform Noise Handshake, initiator side");
+
+    let secret = [
+        NOISE_PSK_PREFIX.to_vec(),
+        remote_pub_key.to_bytes().to_vec(),
+        epoch.to_be_bytes().to_vec(),
+    ]
+    .concat();
+    let secret_hash = Sha256::digest(secret);
+
+    let handshake = Builder::new(pattern.as_str().parse()?)
+        .local_private_key(&local_private_key.to_bytes())
+        .remote_public_key(&remote_pub_key.to_bytes())
+        .psk(pattern.psk_position(), &secret_hash)
+        .build_initiator()?;
+
+    let noise_stream = NoiseStream::new(conn, handshake);
+
+    Ok(Connection::Noise(noise_stream.perform_handshake().await?))
+}
+
+pub async fn upgrade_noise_initiator_with_topology(
+    conn: TcpStream,
+    pattern: NoisePattern,
+    topology: &NymTopology,
+    epoch: u32,
+    local_private_key: &encryption::PrivateKey,
+) -> Result<Connection, NoiseError> {
+    //Get init material
+    let responder_addr = conn.peer_addr().map_err(|err| {
+        error!("Unable to extract peer address from connection - {err}");
+        Error::Prereq(Prerequisite::RemotePublicKey)
+    })?;
+
+    let remote_pub_key = match topology.find_node_key_by_mix_host(responder_addr, true) {
+        Ok(Some(key)) => encryption::PublicKey::from_base58_string(key)?,
+        Ok(None) => {
+            warn!(
+                "{:?} can't speak Noise yet, falling back to TCP",
+                responder_addr
+            );
+            return Ok(Connection::Tcp(conn));
+        }
+        Err(_) => {
+            error!(
+                "Cannot find public key for node with address {:?}",
+                responder_addr
+            ); //Do we still pursue a TCP connection or not?
+            return Err(Error::Prereq(Prerequisite::RemotePublicKey).into());
+        }
+    };
+
+    upgrade_noise_initiator(conn, pattern, local_private_key, &remote_pub_key, epoch).await
+}
+
+pub async fn upgrade_noise_responder(
+    conn: TcpStream,
+    pattern: NoisePattern,
+    local_public_key: &encryption::PublicKey,
+    local_private_key: &encryption::PrivateKey,
+    epoch: u32,
+) -> Result<Connection, NoiseError> {
+    trace!("Perform Noise Handshake, responder side");
+
+    let secret = [
+        NOISE_PSK_PREFIX.to_vec(),
+        local_public_key.to_bytes().to_vec(),
+        epoch.to_be_bytes().to_vec(),
+    ]
+    .concat();
+    let secret_hash = Sha256::digest(secret);
+
+    let handshake = Builder::new(pattern.as_str().parse()?)
+        .local_private_key(&local_private_key.to_bytes())
+        .psk(pattern.psk_position(), &secret_hash)
+        .build_responder()?;
+
+    let noise_stream = NoiseStream::new(conn, handshake);
+
+    Ok(Connection::Noise(noise_stream.perform_handshake().await?))
+}
+
+pub async fn upgrade_noise_responder_with_topology(
+    conn: TcpStream,
+    pattern: NoisePattern,
+    topology: &NymTopology,
+    epoch: u32,
+    local_public_key: &encryption::PublicKey,
+    local_private_key: &encryption::PrivateKey,
+) -> Result<Connection, NoiseError> {
+    //Get init material
+    let initiator_addr = match conn.peer_addr() {
+        Ok(addr) => addr,
+        Err(err) => {
+            error!("Unable to extract peer address from connection - {err}");
+            return Err(Error::Prereq(Prerequisite::RemotePublicKey).into());
+        }
+    };
+
+    match topology.find_node_key_by_mix_host(initiator_addr, false) {
+        Ok(Some(_)) => {
+            //Existing node supporting Noise
+            upgrade_noise_responder(conn, pattern, local_public_key, local_private_key, epoch).await
+        }
+        Ok(None) => {
+            //Existing node not supporting Noise yet
+            warn!(
+                "{:?} can't speak Noise yet, falling back to TCP",
+                initiator_addr
+            );
+            Ok(Connection::Tcp(conn))
+        }
+        Err(_) => {
+            //Non existing node
+            error!(
+                "Cannot find public key for node with address {:?}",
+                initiator_addr
+            ); //Do we still pursue a TCP connection with that node or not?
+            Err(Error::Prereq(Prerequisite::RemotePublicKey).into())
+        }
+    }
+}

common/nymnoise/src/stream.rs

@@ -0,0 +1,220 @@
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: GPL-3.0-only
+
+use crate::error::NoiseError;
+use bytes::BytesMut;
+use futures::{Sink, SinkExt, Stream, StreamExt};
+use pin_project::pin_project;
+use snow::{HandshakeState, TransportState};
+use std::cmp::min;
+use std::collections::VecDeque;
+use std::io;
+use std::pin::Pin;
+use std::task::Poll;
+use tokio::{
+    io::{AsyncRead, AsyncWrite, ReadBuf},
+    net::TcpStream,
+};
+use tokio_util::codec::{Framed, LengthDelimitedCodec};
+
+const MAXMSGLEN: usize = 65535;
+const TAGLEN: usize = 16;
+
+#[derive(Default)]
+pub enum NoisePattern {
+    #[default]
+    XKpsk3,
+    IKpsk2,
+}
+
+impl NoisePattern {
+    pub(crate) fn as_str(&self) -> &'static str {
+        match self {
+            Self::XKpsk3 => "Noise_XKpsk3_25519_AESGCM_SHA256",
+            Self::IKpsk2 => "Noise_IKpsk2_25519_ChaChaPoly_BLAKE2s", //Wireguard handshake (not exactly though)
+        }
+    }
+
+    pub(crate) fn psk_position(&self) -> u8 {
+        //automatic parsing, works for correct pattern, more convenient
+        match self.as_str().find("psk") {
+            Some(n) => {
+                let psk_index = n + 3;
+                let psk_char = self.as_str().chars().nth(psk_index).unwrap();
+                psk_char.to_string().parse().unwrap()
+                //if this fails, it means hardcoded pattern are wrong
+            }
+            None => 0,
+        }
+    }
+}
+
+/// Wrapper around a TcpStream
+#[pin_project]
+pub struct NoiseStream {
+    #[pin]
+    inner_stream: Framed<TcpStream, LengthDelimitedCodec>,
+    handshake: Option<HandshakeState>,
+    noise: Option<TransportState>,
+    dec_buffer: VecDeque<u8>,
+}
+
+impl NoiseStream {
+    pub(crate) fn new(inner_stream: TcpStream, handshake: HandshakeState) -> NoiseStream {
+        NoiseStream {
+            inner_stream: LengthDelimitedCodec::builder()
+                .length_field_type::<u16>()
+                .new_framed(inner_stream),
+            handshake: Some(handshake),
+            noise: None,
+            dec_buffer: VecDeque::with_capacity(MAXMSGLEN),
+        }
+    }
+
+    pub(crate) async fn perform_handshake(mut self) -> Result<Self, NoiseError> {
+        //Check if we are in the correct state
+        let Some(mut handshake) = self.handshake else {
+            return Err(NoiseError::IncorrectStateError);
+        };
+        self.handshake = None;
+
+        while !handshake.is_handshake_finished() {
+            if handshake.is_my_turn() {
+                self.send_handshake_msg(&mut handshake).await?;
+            } else {
+                self.recv_handshake_msg(&mut handshake).await?;
+            }
+        }
+
+        self.noise = Some(handshake.into_transport_mode()?);
+        Ok(self)
+    }
+
+    async fn send_handshake_msg(
+        &mut self,
+        handshake: &mut HandshakeState,
+    ) -> Result<(), NoiseError> {
+        let mut buf = BytesMut::zeroed(MAXMSGLEN + TAGLEN);
+        let len = handshake.write_message(&[], &mut buf)?;
+        buf.truncate(len);
+        self.inner_stream.send(buf.into()).await?;
+        Ok(())
+    }
+
+    async fn recv_handshake_msg(
+        &mut self,
+        handshake: &mut HandshakeState,
+    ) -> Result<(), NoiseError> {
+        match self.inner_stream.next().await {
+            Some(Ok(msg)) => {
+                let mut buf = vec![0u8; MAXMSGLEN];
+                handshake.read_message(&msg, &mut buf)?;
+                Ok(())
+            }
+            Some(Err(err)) => Err(NoiseError::IoError(err)),
+            None => Err(NoiseError::HandshakeError),
+        }
+    }
+
+    pub fn peer_addr(&self) -> Result<std::net::SocketAddr, io::Error> {
+        self.inner_stream.get_ref().peer_addr()
+    }
+}
+
+impl AsyncRead for NoiseStream {
+    fn poll_read(
+        self: Pin<&mut Self>,
+        cx: &mut std::task::Context<'_>,
+        buf: &mut ReadBuf<'_>,
+    ) -> Poll<std::io::Result<()>> {
+        let projected_self = self.project();
+
+        match projected_self.inner_stream.poll_next(cx) {
+            Poll::Pending => {
+                //no new data, waking is already scheduled.
+                //Nothing new to decrypt, only check if we can return something from dec_storage, happens after
+            }
+
+            Poll::Ready(Some(Ok(noise_msg))) => {
+                //We have a new moise msg
+                let mut dec_msg = vec![0u8; MAXMSGLEN];
+                let len = match projected_self.noise {
+                    Some(transport_state) => {
+                        match transport_state.read_message(&noise_msg, &mut dec_msg) {
+                            Ok(len) => len,
+                            Err(_) => return Poll::Ready(Err(io::ErrorKind::InvalidInput.into())),
+                        }
+                    }
+                    None => return Poll::Ready(Err(io::ErrorKind::Other.into())),
+                };
+                projected_self.dec_buffer.extend(&dec_msg[..len]);
+            }
+
+            Poll::Ready(Some(Err(err))) => return Poll::Ready(Err(err)),
+
+            //Stream is done, return Ok with nothing in buf
+            Poll::Ready(None) => return Poll::Ready(Ok(())),
+        }
+
+        //check and return what we can
+        let read_len = min(buf.remaining(), projected_self.dec_buffer.len());
+        if read_len > 0 {
+            buf.put_slice(
+                &projected_self
+                    .dec_buffer
+                    .drain(..read_len)
+                    .collect::<Vec<u8>>(),
+            );
+            return Poll::Ready(Ok(()));
+        }
+
+        //If we end up here, it must mean the previous poll_next was pending as well, otherwise something was returned. Hence waking is already scheduled
+        Poll::Pending
+    }
+}
+
+impl AsyncWrite for NoiseStream {
+    fn poll_write(
+        self: Pin<&mut Self>,
+        cx: &mut std::task::Context<'_>,
+        buf: &[u8],
+    ) -> Poll<Result<usize, std::io::Error>> {
+        let mut projected_self = self.project();
+
+        match projected_self.inner_stream.as_mut().poll_ready(cx) {
+            Poll::Pending => Poll::Pending,
+
+            Poll::Ready(Err(err)) => Poll::Ready(Err(err)),
+
+            Poll::Ready(Ok(())) => {
+                let mut noise_buf = BytesMut::zeroed(MAXMSGLEN + TAGLEN);
+
+                let Ok(len) = (match projected_self.noise {
+                    Some(transport_state) => transport_state.write_message(buf, &mut noise_buf),
+                    None => return Poll::Ready(Err(io::ErrorKind::Other.into())),
+                }) else {
+                    return Poll::Ready(Err(io::ErrorKind::InvalidInput.into()));
+                };
+                noise_buf.truncate(len);
+                match projected_self.inner_stream.start_send(noise_buf.into()) {
+                    Ok(()) => Poll::Ready(Ok(buf.len())),
+                    Err(e) => Poll::Ready(Err(e)),
+                }
+            }
+        }
+    }
+
+    fn poll_flush(
+        self: Pin<&mut Self>,
+        cx: &mut std::task::Context<'_>,
+    ) -> Poll<Result<(), std::io::Error>> {
+        self.project().inner_stream.poll_flush(cx)
+    }
+
+    fn poll_shutdown(
+        self: Pin<&mut Self>,
+        cx: &mut std::task::Context<'_>,
+    ) -> Poll<Result<(), std::io::Error>> {
+        self.project().inner_stream.poll_close(cx)
+    }
+}

common/nymsphinx/anonymous-replies/Cargo.toml

@@ -9,7 +9,7 @@ repository = { workspace = true }
 
 [dependencies]
 rand = { version = "0.7.3", features = ["wasm-bindgen"] }
-bs58 = "0.4"
+bs58 = { workspace = true }
 serde = { workspace = true }
 thiserror = { workspace = true }
 

common/nymsphinx/src/receiver.rs

@@ -237,7 +237,7 @@ mod message_receiver {
                 mix_id: 123,
                 owner: "foomp1".to_string(),
                 host: "10.20.30.40".parse().unwrap(),
-                mix_host: "10.20.30.40:1789".parse().unwrap(),
+                mix_hosts: vec!["10.20.30.40:1789".parse().unwrap()],
                 identity_key: identity::PublicKey::from_base58_string(
                     "3ebjp1Fb9hdcS1AR6AZihgeJiMHkB5jjJUsvqNnfQwU7",
                 )
@@ -257,7 +257,7 @@ mod message_receiver {
                 mix_id: 234,
                 owner: "foomp2".to_string(),
                 host: "11.21.31.41".parse().unwrap(),
-                mix_host: "11.21.31.41:1789".parse().unwrap(),
+                mix_hosts: vec!["11.21.31.41:1789".parse().unwrap()],
                 identity_key: identity::PublicKey::from_base58_string(
                     "D6YaMzLSY7mANtSQRKXsmMZpqgqiVkeiagKM4V4oFPFr",
                 )
@@ -277,7 +277,7 @@ mod message_receiver {
                 mix_id: 456,
                 owner: "foomp3".to_string(),
                 host: "12.22.32.42".parse().unwrap(),
-                mix_host: "12.22.32.42:1789".parse().unwrap(),
+                mix_hosts: vec!["12.22.32.42:1789".parse().unwrap()],
                 identity_key: identity::PublicKey::from_base58_string(
                     "GkWDysw4AjESv1KiAiVn7JzzCMJeksxNSXVfr1PpX8wD",
                 )
@@ -297,7 +297,7 @@ mod message_receiver {
             vec![gateway::Node {
                 owner: "foomp4".to_string(),
                 host: "1.2.3.4".parse().unwrap(),
-                mix_host: "1.2.3.4:1789".parse().unwrap(),
+                mix_hosts: vec!["1.2.3.4:1789".parse().unwrap()],
                 clients_ws_port: 9000,
                 clients_wss_port: None,
                 identity_key: identity::PublicKey::from_base58_string(