remove import

- updated

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

@@ -9,12 +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 * * *'
+    - cron: "14 0 * * *"
   pull_request:
     paths:
       - "clients/**"
@@ -30,6 +35,7 @@ on:
       - "sdk/rust/nym-sdk/**"
       - "service-providers/**"
       - "tools/**"
+      - "nymvisor/**"
 
 jobs:
   publish-nym:
@@ -84,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'
@@ -105,6 +111,7 @@ 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 or nightly, upload to build server
@@ -122,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 == 'schedule' || github.event_name == 'pull_request'
         continue-on-error: true
         uses: easingthemes/ssh-deploy@main
         env:

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

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

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

@@ -27,13 +27,12 @@ members = [
     "common/client-libs/gateway-client",
     "common/client-libs/mixnet-client",
     "common/client-libs/validator-client",
-    "common/coconut-interface",
     "common/commands",
     "common/config",
     "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",
@@ -43,6 +42,7 @@ members = [
     "common/credential-storage",
     "common/credentials",
     "common/credential-utils",
+    "common/credentials-interface",
     "common/crypto",
     "common/dkg",
     "common/execute",
@@ -104,7 +104,7 @@ 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-nr-query",
     "tools/nymvisor",
@@ -143,6 +143,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 +159,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 +169,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,24 +21,24 @@ 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" }
 nym-bin-common = { path = "../../common/bin-common", features = ["output_format"] }
 nym-client-core = { path = "../../common/client-core", features = ["fs-surb-storage", "cli"] }
-nym-coconut-interface = { path = "../../common/coconut-interface" }
 nym-config = { path = "../../common/config" }
 nym-credential-storage = { path = "../../common/credential-storage" }
 nym-credentials = { path = "../../common/credentials" }

clients/native/src/commands/import_credential.rs

@@ -0,0 +1,101 @@
+// 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 log::{error, info};
+use nym_credential_storage::models::StorableIssuedCredential;
+use nym_credential_storage::storage::Storage;
+use nym_credentials::coconut::bandwidth::issued::BandwidthCredentialIssuedDataVariant;
+use nym_credentials::IssuedBandwidthCredential;
+use std::fs;
+use std::path::PathBuf;
+use zeroize::Zeroizing;
+
+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, default_value_t = 1)]
+    pub(crate) version: 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())?
+        }
+    };
+    let raw_credential = Zeroizing::new(raw_credential);
+
+    // we're unpacking the data in order to make sure it's valid
+    // and to extract relevant metadata for storage purposes
+    let credential = match args.version {
+        1 => Zeroizing::new(
+            IssuedBandwidthCredential::unpack_v1(&raw_credential).map_err(|source| {
+                ClientError::CredentialDeserializationFailure {
+                    storage_revision: 1,
+                    source,
+                }
+            })?,
+        ),
+        other => panic!("unknown credential serialization version {other}"),
+    };
+
+    info!("importing {}", credential.typ());
+    match credential.variant_data() {
+        BandwidthCredentialIssuedDataVariant::Voucher(voucher_info) => {
+            info!("with value of {}", voucher_info.value())
+        }
+        BandwidthCredentialIssuedDataVariant::FreePass(freepass_info) => {
+            info!("with expiry at {}", freepass_info.expiry_date());
+            if freepass_info.expired() {
+                error!("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(ClientError::ExpiredCredentialImport {
+                    expiration: freepass_info.expiry_date(),
+                });
+            }
+        }
+    }
+
+    let storable = StorableIssuedCredential {
+        serialization_revision: args.version,
+        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?;
+    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_credential_storage::error::StorageError;
+use time::OffsetDateTime;
 
 #[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,22 @@ pub enum ClientError {
 
     #[error("Attempted to start the client in invalid socket mode")]
     InvalidSocketMode,
+
+    #[error("failed to store credential: {source}")]
+    CredentialStorageFailure {
+        #[from]
+        source: StorageError,
+    },
+
+    #[error(
+        "failed to deserialize provided credential using revision {storage_revision}: {source}"
+    )]
+    CredentialDeserializationFailure {
+        storage_revision: u8,
+        #[source]
+        source: nym_credentials::error::Error,
+    },
+
+    #[error("attempted to import an expired credential (it expired on {expiration})")]
+    ExpiredCredentialImport { expiration: OffsetDateTime },
 }

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,22 +8,22 @@ 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"] }
 nym-client-core = { path = "../../common/client-core", features = ["fs-surb-storage", "cli"] }
-nym-coconut-interface = { path = "../../common/coconut-interface" }
 nym-config = { path = "../../common/config" }
 nym-credentials = { path = "../../common/credentials" }
 nym-crypto = { path = "../../common/crypto" }

clients/socks5/src/commands/import_credential.rs

@@ -0,0 +1,101 @@
+// 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 log::{error, info};
+use nym_credential_storage::models::StorableIssuedCredential;
+use nym_credential_storage::storage::Storage;
+use nym_credentials::coconut::bandwidth::issued::BandwidthCredentialIssuedDataVariant;
+use nym_credentials::IssuedBandwidthCredential;
+use std::fs;
+use std::path::PathBuf;
+use zeroize::Zeroizing;
+
+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, default_value_t = 1)]
+    pub(crate) version: 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())?
+        }
+    };
+    let raw_credential = Zeroizing::new(raw_credential);
+
+    // we're unpacking the data in order to make sure it's valid
+    // and to extract relevant metadata for storage purposes
+    let credential = match args.version {
+        1 => Zeroizing::new(
+            IssuedBandwidthCredential::unpack_v1(&raw_credential).map_err(|source| {
+                Socks5ClientError::CredentialDeserializationFailure {
+                    storage_revision: 1,
+                    source,
+                }
+            })?,
+        ),
+        other => panic!("unknown credential serialization version {other}"),
+    };
+
+    info!("importing {}", credential.typ());
+    match credential.variant_data() {
+        BandwidthCredentialIssuedDataVariant::Voucher(voucher_info) => {
+            info!("with value of {}", voucher_info.value())
+        }
+        BandwidthCredentialIssuedDataVariant::FreePass(freepass_info) => {
+            info!("with expiry at {}", freepass_info.expiry_date());
+            if freepass_info.expired() {
+                error!("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(Socks5ClientError::ExpiredCredentialImport {
+                    expiration: freepass_info.expiry_date(),
+                });
+            }
+        }
+    }
+
+    let storable = StorableIssuedCredential {
+        serialization_revision: args.version,
+        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?;
+    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};
@@ -24,18 +23,16 @@ use nym_config::OptionalSet;
 use nym_sphinx::params::{PacketSize, PacketType};
 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/error.rs

@@ -1,4 +1,6 @@
 use nym_client_core::error::ClientCoreError;
+use nym_credential_storage::error::StorageError;
+use time::OffsetDateTime;
 
 #[derive(thiserror::Error, Debug)]
 pub enum Socks5ClientError {
@@ -18,6 +20,24 @@ pub enum Socks5ClientError {
     #[error("Fail to bind address")]
     FailToBindAddress,
 
-    #[error("client-core error: {0}")]
+    #[error(transparent)]
     ClientCoreError(#[from] ClientCoreError),
+
+    #[error("failed to store credential: {source}")]
+    CredentialStorageFailure {
+        #[from]
+        source: StorageError,
+    },
+
+    #[error(
+        "failed to deserialize provided credential using revision {storage_revision}: {source}"
+    )]
+    CredentialDeserializationFailure {
+        storage_revision: u8,
+        #[source]
+        source: nym_credentials::error::Error,
+    },
+
+    #[error("attempted to import an expired credential (it expired on {expiration})")]
+    ExpiredCredentialImport { expiration: OffsetDateTime },
 }

common/bandwidth-controller/Cargo.toml

@@ -8,14 +8,16 @@ license.workspace = true
 
 [dependencies]
 bip39 = { workspace = true }
+log = { workspace = true }
 rand = "0.7.3"
 thiserror = { workspace = true }
 url = { workspace = true }
 zeroize = { workspace = true }
 
-nym-coconut-interface = { path = "../coconut-interface" }
+nym-coconut = { path = "../nymcoconut" }
 nym-credential-storage = { path = "../credential-storage" }
 nym-credentials = { path = "../credentials" }
+nym-credentials-interface = { path = "../credentials-interface" }
 nym-crypto = { path = "../crypto", features = ["rand", "asymmetric", "symmetric", "aes", "hashing"] }
 nym-network-defaults = { path = "../network-defaults" }
 nym-validator-client = { path = "../client-libs/validator-client", default-features = false }

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

@@ -2,18 +2,18 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::error::BandwidthControllerError;
-use nym_coconut_interface::Base58;
+use nym_credential_storage::models::StorableIssuedCredential;
 use nym_credential_storage::storage::Storage;
-use nym_credentials::coconut::bandwidth::BandwidthVoucher;
+use nym_credentials::coconut::bandwidth::{CredentialType, IssuanceBandwidthCredential};
 use nym_credentials::coconut::utils::obtain_aggregate_signature;
 use nym_crypto::asymmetric::{encryption, identity};
-use nym_network_defaults::VOUCHER_INFO;
 use nym_validator_client::coconut::all_coconut_api_clients;
 use nym_validator_client::nyxd::contract_traits::CoconutBandwidthSigningClient;
 use nym_validator_client::nyxd::contract_traits::DkgQueryClient;
 use nym_validator_client::nyxd::Coin;
 use rand::rngs::OsRng;
 use state::State;
+use zeroize::Zeroizing;
 
 pub mod state;
 
@@ -24,13 +24,11 @@ where
     let mut rng = OsRng;
     let signing_key = identity::PrivateKey::new(&mut rng);
     let encryption_key = encryption::PrivateKey::new(&mut rng);
-    let params = BandwidthVoucher::default_parameters();
-    let voucher_value = amount.amount.to_string();
 
     let tx_hash = client
         .deposit(
-            amount,
-            String::from(VOUCHER_INFO),
+            amount.clone(),
+            CredentialType::Voucher.to_string(),
             signing_key.public_key().to_base58_string(),
             encryption_key.public_key().to_base58_string(),
             None,
@@ -38,21 +36,15 @@ where
         .await?
         .transaction_hash;
 
-    let voucher = BandwidthVoucher::new(
-        &params,
-        voucher_value,
-        VOUCHER_INFO.to_string(),
-        tx_hash,
-        signing_key,
-        encryption_key,
-    );
+    let voucher =
+        IssuanceBandwidthCredential::new_voucher(amount, tx_hash, signing_key, encryption_key);
 
-    let state = State { voucher, params };
+    let state = State { voucher };
 
     Ok(state)
 }
 
-pub async fn get_credential<C, St>(
+pub async fn get_bandwidth_voucher<C, St>(
     state: &State,
     client: &C,
     storage: &St,
@@ -62,6 +54,9 @@ where
     St: Storage,
     <St as Storage>::StorageError: Send + Sync + 'static,
 {
+    // temporary
+    assert!(state.voucher.typ().is_voucher());
+
     let epoch_id = client.get_current_epoch().await?.epoch_id;
     let threshold = client
         .get_current_epoch_threshold()
@@ -70,22 +65,23 @@ where
 
     let coconut_api_clients = all_coconut_api_clients(client, epoch_id).await?;
 
-    let signature = obtain_aggregate_signature(
-        &state.params,
-        &state.voucher,
-        &coconut_api_clients,
-        threshold,
-    )
-    .await?;
+    let signature =
+        obtain_aggregate_signature(&state.voucher, &coconut_api_clients, threshold).await?;
+    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());
+    let storable = StorableIssuedCredential {
+        serialization_revision: issued.current_serialization_revision(),
+        credential_data: credential_data.as_ref(),
+        credential_type: issued.typ().to_string(),
+        epoch_id: epoch_id
+            .try_into()
+            .expect("our epoch is has run over u32::MAX!"),
+    };
+
     storage
-        .insert_coconut_credential(
-            state.voucher.get_voucher_value(),
-            VOUCHER_INFO.to_string(),
-            state.voucher.get_private_attributes()[0].to_bs58(),
-            state.voucher.get_private_attributes()[1].to_bs58(),
-            signature.to_bs58(),
-            epoch_id.to_string(),
-        )
+        .insert_issued_credential(storable)
         .await
         .map_err(|err| BandwidthControllerError::CredentialStorageError(Box::new(err)))
 }

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

@@ -1,19 +1,14 @@
-// Copyright 2022-2023 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2022-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
-use nym_coconut_interface::Parameters;
-use nym_credentials::coconut::bandwidth::BandwidthVoucher;
+use nym_credentials::coconut::bandwidth::IssuanceBandwidthCredential;
 
 pub struct State {
-    pub voucher: BandwidthVoucher,
-    pub params: Parameters,
+    pub voucher: IssuanceBandwidthCredential,
 }
 
 impl State {
-    pub fn new(voucher: BandwidthVoucher) -> Self {
-        State {
-            voucher,
-            params: BandwidthVoucher::default_parameters(),
-        }
+    pub fn new(voucher: IssuanceBandwidthCredential) -> Self {
+        State { voucher }
     }
 }

common/bandwidth-controller/src/error.rs

@@ -1,7 +1,7 @@
 // Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
-use nym_coconut_interface::CoconutError;
+use nym_coconut::CoconutError;
 use nym_credential_storage::error::StorageError;
 use nym_credentials::error::Error as CredentialsError;
 use nym_crypto::asymmetric::encryption::KeyRecoveryError;
@@ -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),
@@ -45,4 +48,7 @@ pub enum BandwidthControllerError {
 
     #[error("Threshold not set yet")]
     NoThreshold,
+
+    #[error("can't handle recovering storage with revision {stored}. {expected} was expected")]
+    UnsupportedCredentialStorageRevision { stored: u8, expected: u8 },
 }

common/bandwidth-controller/src/lib.rs

@@ -1,80 +1,140 @@
-// Copyright 2021-2023 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2021-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::error::BandwidthControllerError;
-use nym_credential_storage::error::StorageError;
+use crate::utils::stored_credential_to_issued_bandwidth;
+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;
 use nym_validator_client::nyxd::contract_traits::DkgQueryClient;
-use std::str::FromStr;
-use zeroize::Zeroizing;
-use {
-    nym_coconut_interface::Base58,
-    nym_credentials::coconut::{
-        bandwidth::prepare_for_spending, utils::obtain_aggregate_verification_key,
-    },
-};
 
 pub mod acquire;
 pub mod error;
+mod utils;
 
 pub struct BandwidthController<C, St> {
     storage: St,
     client: C,
 }
 
+pub struct PreparedCredential {
+    /// The cryptographic material required for spending the underlying credential.
+    pub data: CredentialSpendingData,
+
+    /// 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: EpochId,
+
+    /// The database id of the stored credential.
+    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
     }
 
-    pub async fn prepare_coconut_credential(
+    async fn get_aggregate_verification_key(
         &self,
-    ) -> Result<(nym_coconut_interface::Credential, i64), BandwidthControllerError>
+        epoch_id: EpochId,
+    ) -> Result<VerificationKey, BandwidthControllerError>
     where
         C: DkgQueryClient + Sync + Send,
         <St as Storage>::StorageError: Send + Sync + 'static,
     {
-        let bandwidth_credential = self
-            .storage
-            .get_next_coconut_credential()
-            .await
-            .map_err(|err| BandwidthControllerError::CredentialStorageError(Box::new(err)))?;
-        let voucher_value = u64::from_str(&bandwidth_credential.voucher_value)
-            .map_err(|_| StorageError::InconsistentData)?;
-        let voucher_info = bandwidth_credential.voucher_info.clone();
-        let serial_number = Zeroizing::new(nym_coconut_interface::Attribute::try_from_bs58(
-            bandwidth_credential.serial_number,
-        )?);
-        let binding_number = Zeroizing::new(nym_coconut_interface::Attribute::try_from_bs58(
-            bandwidth_credential.binding_number,
-        )?);
-        let signature =
-            nym_coconut_interface::Signature::try_from_bs58(bandwidth_credential.signature)?;
-        let epoch_id = u64::from_str(&bandwidth_credential.epoch_id)
-            .map_err(|_| StorageError::InconsistentData)?;
-
         let coconut_api_clients = all_coconut_api_clients(&self.client, epoch_id).await?;
+        Ok(obtain_aggregate_verification_key(&coconut_api_clients)?)
+    }
 
-        let verification_key = obtain_aggregate_verification_key(&coconut_api_clients).await?;
+    pub async fn prepare_bandwidth_credential(
+        &self,
+    ) -> Result<PreparedCredential, BandwidthControllerError>
+    where
+        C: DkgQueryClient + Sync + Send,
+        <St as Storage>::StorageError: Send + Sync + 'static,
+    {
+        let retrieved_credential = self.get_next_usable_credential().await?;
 
-        // the below would only be executed once we know where we want to spend it (i.e. which gateway and stuff)
-        Ok((
-            prepare_for_spending(
-                voucher_value,
-                voucher_info,
-                &serial_number,
-                &binding_number,
-                epoch_id,
-                &signature,
-                &verification_key,
-            )?,
-            bandwidth_credential.id,
-        ))
+        let epoch_id = retrieved_credential.credential.epoch_id();
+        let credential_id = retrieved_credential.credential_id;
+
+        let verification_key = self.get_aggregate_verification_key(epoch_id).await?;
+
+        let spend_request = retrieved_credential
+            .credential
+            .prepare_for_spending(&verification_key)?;
+
+        Ok(PreparedCredential {
+            data: spend_request,
+            epoch_id,
+            credential_id,
+        })
     }
 
     pub async fn consume_credential(&self, id: i64) -> Result<(), BandwidthControllerError>
@@ -93,7 +153,7 @@ impl<C, St: Storage> BandwidthController<C, St> {
 impl<C, St> Clone for BandwidthController<C, St>
 where
     C: Clone,
-    St: Storage + Clone,
+    St: Clone,
 {
     fn clone(&self) -> Self {
         BandwidthController {

common/bandwidth-controller/src/utils.rs

@@ -0,0 +1,22 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::error::BandwidthControllerError;
+use nym_credential_storage::models::StoredIssuedCredential;
+use nym_credentials::coconut::bandwidth::issued::CURRENT_SERIALIZATION_REVISION;
+use nym_credentials::coconut::bandwidth::IssuedBandwidthCredential;
+
+pub fn stored_credential_to_issued_bandwidth(
+    cred: StoredIssuedCredential,
+) -> Result<IssuedBandwidthCredential, BandwidthControllerError> {
+    if cred.serialization_revision != CURRENT_SERIALIZATION_REVISION {
+        return Err(
+            BandwidthControllerError::UnsupportedCredentialStorageRevision {
+                stored: cred.serialization_revision,
+                expected: CURRENT_SERIALIZATION_REVISION,
+            },
+        );
+    }
+
+    Ok(IssuedBandwidthCredential::unpack_v1(&cred.credential_data)?)
+}

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

@@ -52,6 +52,7 @@ use nym_topology::provider_trait::TopologyProvider;
 use nym_topology::HardcodedTopologyProvider;
 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 +104,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 +673,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 +767,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/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-libs/gateway-client/Cargo.toml

@@ -19,7 +19,7 @@ tokio = { version = "1.24.1", features = ["macros"] }
 
 # internal
 nym-bandwidth-controller = { path = "../../bandwidth-controller" }
-nym-coconut-interface = { path = "../../coconut-interface" }
+nym-credentials = { path = "../../credentials" }
 nym-credential-storage = { path = "../../credential-storage" }
 nym-crypto = { path = "../../crypto" }
 nym-gateway-requests = { path = "../../../gateway/gateway-requests" }
@@ -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

@@ -1,4 +1,4 @@
-// Copyright 2021-2023 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2021-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::error::GatewayClientError;
@@ -6,20 +6,23 @@ 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};
 use log::*;
 use nym_bandwidth_controller::BandwidthController;
-use nym_coconut_interface::Credential;
 use nym_credential_storage::ephemeral_storage::EphemeralStorage as EphemeralCredentialStorage;
 use nym_credential_storage::storage::Storage as CredentialStorage;
+use nym_credentials::CredentialSpendingData;
 use nym_crypto::asymmetric::identity;
 use nym_gateway_requests::authentication::encrypted_address::EncryptedAddressBytes;
 use nym_gateway_requests::iv::IV;
 use nym_gateway_requests::registration::handshake::{client_handshake, SharedKeys};
-use nym_gateway_requests::{BinaryRequest, ClientControlRequest, ServerResponse, PROTOCOL_VERSION};
+use nym_gateway_requests::{
+    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;
@@ -30,11 +33,15 @@ use std::sync::Arc;
 use std::time::Duration;
 use tungstenite::protocol::Message;
 
+#[cfg(not(target_arch = "wasm32"))]
+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(target_arch = "wasm32")]
+use std::os::raw::c_int as RawFd;
 #[cfg(target_arch = "wasm32")]
 use wasm_utils::websocket::JSWebsocket;
 #[cfg(target_arch = "wasm32")]
@@ -79,6 +86,9 @@ pub struct GatewayClient<C, St = EphemeralCredentialStorage> {
     /// Delay between each subsequent reconnection attempt.
     reconnection_backoff: Duration,
 
+    // currently unused (but populated)
+    negotiated_protocol: Option<u8>,
+
     /// Listen to shutdown messages.
     shutdown: TaskClient,
 }
@@ -108,6 +118,7 @@ impl<C, St> GatewayClient<C, St> {
             should_reconnect_on_failure: true,
             reconnection_attempts: DEFAULT_RECONNECTION_ATTEMPTS,
             reconnection_backoff: DEFAULT_RECONNECTION_BACKOFF,
+            negotiated_protocol: None,
             shutdown,
         }
     }
@@ -146,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
     }
@@ -376,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 => {
@@ -383,17 +404,17 @@ impl<C, St> GatewayClient<C, St> {
                 // note: in +1.2.0 we will have to return a hard error here
                 Ok(())
             }
-            Some(v) if v != PROTOCOL_VERSION => {
+            Some(v) if v > CURRENT_PROTOCOL_VERSION => {
                 let err = GatewayClientError::IncompatibleProtocol {
                     gateway: Some(v),
-                    current: PROTOCOL_VERSION,
+                    current: CURRENT_PROTOCOL_VERSION,
                 };
                 error!("{err}");
                 Err(err)
             }
 
             Some(_) => {
-                info!("the gateway is using exactly the same protocol version as we are. We're good to continue!");
+                info!("the gateway is using exactly the same (or older) protocol version as we are. We're good to continue!");
                 Ok(())
             }
         }
@@ -439,6 +460,10 @@ impl<C, St> GatewayClient<C, St> {
         if self.authenticated {
             self.shared_key = Some(Arc::new(shared_key));
         }
+
+        // populate the negotiated protocol for future uses
+        self.negotiated_protocol = gateway_protocol;
+
         Ok(())
     }
 
@@ -481,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)),
@@ -515,13 +541,13 @@ impl<C, St> GatewayClient<C, St> {
 
     async fn claim_coconut_bandwidth(
         &mut self,
-        credential: Credential,
+        credential: CredentialSpendingData,
     ) -> Result<(), GatewayClientError> {
         let mut rng = OsRng;
         let iv = IV::new_random(&mut rng);
 
-        let msg = ClientControlRequest::new_enc_coconut_bandwidth_credential(
-            &credential,
+        let msg = ClientControlRequest::new_enc_coconut_bandwidth_credential_v2(
+            credential,
             self.shared_key.as_ref().unwrap(),
             iv,
         )
@@ -567,18 +593,31 @@ impl<C, St> GatewayClient<C, St> {
             return self.try_claim_testnet_bandwidth().await;
         }
 
-        let (credential, credential_id) = self
+        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()
             .unwrap()
-            .prepare_coconut_credential()
+            .prepare_bandwidth_credential()
             .await?;
 
-        self.claim_coconut_bandwidth(credential).await?;
+        self.claim_coconut_bandwidth(prepared_credential.data)
+            .await?;
         self.bandwidth_controller
             .as_ref()
             .unwrap()
-            .consume_credential(credential_id)
+            .consume_credential(prepared_credential.credential_id)
             .await?;
 
         Ok(())
@@ -817,6 +856,7 @@ impl GatewayClient<InitOnly, EphemeralCredentialStorage> {
             should_reconnect_on_failure: false,
             reconnection_attempts: DEFAULT_RECONNECTION_ATTEMPTS,
             reconnection_backoff: DEFAULT_RECONNECTION_BACKOFF,
+            negotiated_protocol: None,
             shutdown,
         }
     }
@@ -848,6 +888,7 @@ impl GatewayClient<InitOnly, EphemeralCredentialStorage> {
             should_reconnect_on_failure: self.should_reconnect_on_failure,
             reconnection_attempts: self.reconnection_attempts,
             reconnection_backoff: self.reconnection_backoff,
+            negotiated_protocol: self.negotiated_protocol,
             shutdown,
         }
     }

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(not(target_arch = "wasm32"))]
+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(not(target_arch = "wasm32"))]
+    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(target_arch = "wasm32")]
+    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/validator-client/Cargo.toml

@@ -31,9 +31,8 @@ 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-interface = { path = "../../coconut-interface" }
+nym-coconut = { path = "../../nymcoconut" }
 nym-network-defaults = { path = "../../network-defaults" }
 nym-api-requests = { path = "../../../nym-api/nym-api-requests" }
 
@@ -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,8 +8,10 @@ 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::{
@@ -348,4 +350,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/coconut/mod.rs

@@ -4,9 +4,9 @@
 use crate::nyxd::contract_traits::{DkgQueryClient, PagedDkgQueryClient};
 use crate::nyxd::error::NyxdError;
 use crate::NymApiClient;
+use nym_coconut::{Base58, CoconutError, VerificationKey};
 use nym_coconut_dkg_common::types::{EpochId, NodeIndex};
 use nym_coconut_dkg_common::verification_key::ContractVKShare;
-use nym_coconut_interface::{Base58, CoconutError, VerificationKey};
 use thiserror::Error;
 use url::Url;
 

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

@@ -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)]
@@ -373,6 +375,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

@@ -15,6 +15,8 @@ pub const REWARDED: &str = "rewarded";
 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/contract_traits/mod.rs

@@ -71,6 +71,8 @@ pub trait NymContractsProvider {
     // SPs
     fn name_service_contract_address(&self) -> Option<&AccountId>;
     fn service_provider_contract_address(&self) -> Option<&AccountId>;
+    // swapper
+    fn swapper_contract_address(&self) -> Option<&AccountId>;
 }
 
 #[derive(Debug, Clone)]
@@ -87,6 +89,7 @@ pub struct TypedNymContracts {
 
     pub service_provider_directory_contract_address: Option<AccountId>,
     pub name_service_contract_address: Option<AccountId>,
+    pub swapper_contract_address: Option<AccountId>,
 }
 
 impl TryFrom<NymContracts> for TypedNymContracts {
@@ -130,6 +133,10 @@ impl TryFrom<NymContracts> for TypedNymContracts {
                 .name_service_contract_address
                 .map(|addr| addr.parse())
                 .transpose()?,
+            swapper_contract_address: value
+                .swapper_contract_address
+                .map(|addr| addr.parse())
+                .transpose()?,
         })
     }
 }

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

@@ -140,9 +140,6 @@ pub enum NyxdError {
     #[error("Cosmwasm std error: {0}")]
     CosmwasmStdError(#[from] cosmwasm_std::StdError),
 
-    #[error("Coconut interface error: {0}")]
-    CoconutInterfaceError(#[from] nym_coconut_interface::error::CoconutInterfaceError),
-
     #[error("Account had an unexpected bech32 prefix. Expected: {expected}, got: {got}")]
     UnexpectedBech32Prefix { got: String, expected: String },
 }

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

@@ -292,6 +292,9 @@ impl<C, S> NymContractsProvider for NyxdClient<C, S> {
     fn name_service_contract_address(&self) -> Option<&AccountId> {
         self.config.contracts.name_service_contract_address.as_ref()
     }
+    fn swapper_contract_address(&self) -> Option<&AccountId> {
+        self.config.contracts.swapper_contract_address.as_ref()
+    }
 
     fn service_provider_contract_address(&self) -> Option<&AccountId> {
         self.config
@@ -358,6 +361,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/coconut-interface/Cargo.toml

@@ -1,14 +0,0 @@
-[package]
-name = "nym-coconut-interface"
-version = "0.1.0"
-edition = "2021"
-description = "Crutch library until there is proper SerDe support for coconut structs"
-license.workspace = true
-
-[dependencies]
-bs58 = "0.4.0"
-getset = "0.1.1"
-serde = { workspace = true, features = ["derive"] }
-thiserror = { workspace = true }
-
-nym-coconut = {path = "../nymcoconut" }

common/coconut-interface/src/error.rs

@@ -1,17 +0,0 @@
-// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0
-
-use nym_coconut::CoconutError;
-use thiserror::Error;
-
-#[derive(Debug, Error)]
-pub enum CoconutInterfaceError {
-    #[error("not enough bytes: {0} received, minimum {1} required")]
-    InvalidByteLength(usize, usize),
-
-    #[error("Could not decode base 58 string - {0}")]
-    MalformedString(#[from] bs58::decode::Error),
-
-    #[error("Coconut error - {0}")]
-    CoconutError(#[from] CoconutError),
-}

common/coconut-interface/src/lib.rs

@@ -1,196 +0,0 @@
-// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0
-
-pub mod error;
-
-use getset::{CopyGetters, Getters};
-use serde::{Deserialize, Serialize};
-
-use error::CoconutInterfaceError;
-
-// We list these explicity instead of glob export due to shadowing warnings with the pub tests
-// module.
-pub use nym_coconut::{
-    aggregate_signature_shares, aggregate_verification_keys, blind_sign, hash_to_scalar,
-    prepare_blind_sign, prove_bandwidth_credential, Attribute, Base58, BlindSignRequest,
-    BlindedSignature, Bytable, CoconutError, KeyPair, Parameters, PrivateAttribute,
-    PublicAttribute, SecretKey, Signature, SignatureShare, Theta, VerificationKey,
-};
-
-#[derive(Debug, Serialize, Deserialize, Getters, CopyGetters, Clone, PartialEq, Eq)]
-pub struct Credential {
-    #[getset(get = "pub")]
-    n_params: u32,
-
-    #[getset(get = "pub")]
-    theta: Theta,
-
-    voucher_value: u64,
-
-    voucher_info: String,
-
-    #[getset(get = "pub")]
-    epoch_id: u64,
-}
-impl Credential {
-    pub fn new(
-        n_params: u32,
-        theta: Theta,
-        voucher_value: u64,
-        voucher_info: String,
-        epoch_id: u64,
-    ) -> Credential {
-        Credential {
-            n_params,
-            theta,
-            voucher_value,
-            voucher_info,
-            epoch_id,
-        }
-    }
-
-    pub fn blinded_serial_number(&self) -> String {
-        self.theta.blinded_serial_number_bs58()
-    }
-
-    pub fn has_blinded_serial_number(
-        &self,
-        blinded_serial_number_bs58: &str,
-    ) -> Result<bool, CoconutInterfaceError> {
-        Ok(self
-            .theta
-            .has_blinded_serial_number(blinded_serial_number_bs58)?)
-    }
-
-    pub fn voucher_value(&self) -> u64 {
-        self.voucher_value
-    }
-
-    pub fn verify(&self, verification_key: &VerificationKey) -> bool {
-        let params = Parameters::new(self.n_params).unwrap();
-
-        let hashed_value = hash_to_scalar(self.voucher_value.to_string());
-        let hashed_info = hash_to_scalar(&self.voucher_info);
-        let public_attributes = &[&hashed_value, &hashed_info];
-
-        nym_coconut::verify_credential(&params, verification_key, &self.theta, public_attributes)
-    }
-
-    pub fn as_bytes(&self) -> Vec<u8> {
-        let n_params_bytes = self.n_params.to_be_bytes();
-        let theta_bytes = self.theta.to_bytes();
-        let theta_bytes_len = theta_bytes.len();
-        let voucher_value_bytes = self.voucher_value.to_be_bytes();
-        let epoch_id_bytes = self.epoch_id.to_be_bytes();
-        let voucher_info_bytes = self.voucher_info.as_bytes();
-        let voucher_info_len = voucher_info_bytes.len();
-
-        let mut bytes = Vec::with_capacity(28 + theta_bytes_len + voucher_info_len);
-        bytes.extend_from_slice(&n_params_bytes);
-        bytes.extend_from_slice(&(theta_bytes_len as u64).to_be_bytes());
-        bytes.extend_from_slice(&theta_bytes);
-        bytes.extend_from_slice(&voucher_value_bytes);
-        bytes.extend_from_slice(&epoch_id_bytes);
-        bytes.extend_from_slice(voucher_info_bytes);
-
-        bytes
-    }
-
-    pub fn from_bytes(bytes: &[u8]) -> Result<Self, CoconutError> {
-        if bytes.len() < 28 {
-            return Err(CoconutError::Deserialization(String::from(
-                "To few bytes in credential",
-            )));
-        }
-        let mut four_byte = [0u8; 4];
-        let mut eight_byte = [0u8; 8];
-
-        four_byte.copy_from_slice(&bytes[..4]);
-        let n_params = u32::from_be_bytes(four_byte);
-        eight_byte.copy_from_slice(&bytes[4..12]);
-        let theta_len = u64::from_be_bytes(eight_byte);
-        if bytes.len() < 28 + theta_len as usize {
-            return Err(CoconutError::Deserialization(String::from(
-                "To few bytes in credential",
-            )));
-        }
-        let theta = Theta::from_bytes(&bytes[12..12 + theta_len as usize])
-            .map_err(|e| CoconutError::Deserialization(e.to_string()))?;
-        eight_byte.copy_from_slice(&bytes[12 + theta_len as usize..20 + theta_len as usize]);
-        let voucher_value = u64::from_be_bytes(eight_byte);
-        eight_byte.copy_from_slice(&bytes[20 + theta_len as usize..28 + theta_len as usize]);
-        let epoch_id = u64::from_be_bytes(eight_byte);
-        let voucher_info = String::from_utf8(bytes[28 + theta_len as usize..].to_vec())
-            .map_err(|e| CoconutError::Deserialization(e.to_string()))?;
-
-        Ok(Credential {
-            n_params,
-            theta,
-            voucher_value,
-            voucher_info,
-            epoch_id,
-        })
-    }
-}
-
-impl Bytable for Credential {
-    fn to_byte_vec(&self) -> Vec<u8> {
-        self.as_bytes()
-    }
-
-    fn try_from_byte_slice(slice: &[u8]) -> Result<Self, CoconutError> {
-        Credential::from_bytes(slice)
-    }
-}
-
-impl Base58 for Credential {}
-
-#[cfg(test)]
-mod tests {
-    use nym_coconut::{prove_bandwidth_credential, Signature};
-
-    use super::*;
-
-    #[test]
-    fn serde_coconut_credential() {
-        let voucher_value = 1000000u64;
-        let voucher_info = String::from("BandwidthVoucher");
-        let serial_number =
-            Attribute::try_from_bs58("7Rp3imcuNX3w9se9wm5th8gSvc2czsnMrGsdt5HsrycA").unwrap();
-        let binding_number =
-            Attribute::try_from_bs58("Auf8yVEgyEAWNHaXUZmimS4n9g5YiYnNYqp6F9BtBe9E").unwrap();
-        let signature = Signature::try_from_bs58(
-            "ta3pM9ffj5T6YGbwjSBp2W118rcwyP9PXStc\
-        7ssb91g5GQYMQHhuTNajbdZcjxUFBFL5rhED8EHpRzE8r432ss3qbPBfpNev4CdkfMkQ3wepyM7hy7q1W6Rn9WmFoZL\
-        ZR9j",
-        )
-        .unwrap();
-        let params = Parameters::new(4).unwrap();
-        let verification_key = VerificationKey::try_from_bs58("8CFtVVXdwLy4WHMQPE4\
-        woe89q3DRHoNxBSchftrEjSBPWA4r4xZv4Y9qSvS5x5bMmFtp7BX6ikECAnuXr5EjXWSsgjirZJmpS5XDUynVfht1cD\
-        FWGDvy2XFrRCuoCMotNXi3PoF6wYqdTR9Rqcfoj3i2H5Nid422WBaLtVoC9QNobvpvaqq6vX5PbsSyPayvU8HCXFxM6\
-        JjScYpbRTxQtdwefWLrk3LmXyJQBWi7c2VAhSxu9msp7VTBycqdwQNgxHETStZuwXsozxaGQ2KssVUCaaoYPR4g2RqK\
-        UAvtWwA7pMiAQNcbkXcbsjCgVjWaCpMWC37XA31cLcFf3zbjHD9e5tXjAcqa4M89fbFhuvvSXxowSAZ5NoWrN32kd5d\
-        wxJm1JW3Tt2h6yDDBe84oMy71462dZn7N78DVk2mFNGwBCibrZWA7oUzRBMfYxiQrksoFcou7QfLLd58zoNYmPQPt84\
-        1VpQopEBfdQ7Nf9zoXxBt3zMy7g5NsFGvzh7KTbDUyeeXrdkKJPQBs6dqaizr9sS8CPPmR4uk96vDTRh8CJ5FbSsmb8\
-        nP71dRvvwRZJHGzwYirMo6SXS3ZYxFuiA3mkxYuqDHCwkTWDuRCcAaztrDYRZg7VCMo4Q446AaEso5eqpeWpHZQt53E\
-        ZRpqmNYKASGwMhTeEHPSLgSmtoAAUcaRWpGRzYfd6kzEma8tdGLwyP4rLXgvSvtDLP37dU7YgF3LEXbGAz57U9ATy46\
-        6sroLpHPdaCWB8RF11wvB6Tu196JnJd2KyQBP1iUWP3rtZs3GhAF1QVcxquh8BqDZzAcpQ6wCS1P9c5GxKgww77FVF5\
-        Kp83XtoxSrw3GaYVyKTGxNh3vcKPR31txCjTxPaN2fg7TaPLhoQJX4YaAroFSXqrqbbRsisuHhhCeUP2YwDjHedes9y")
-            .unwrap();
-        let theta = prove_bandwidth_credential(
-            &params,
-            &verification_key,
-            &signature,
-            &serial_number,
-            &binding_number,
-        )
-        .unwrap();
-        let credential = Credential::new(4, theta, voucher_value, voucher_info, 42);
-
-        let serialized_credential = credential.as_bytes();
-        let deserialized_credential = Credential::from_bytes(&serialized_credential).unwrap();
-
-        assert_eq!(credential, deserialized_credential);
-    }
-}

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,6 +52,7 @@ 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" }
 

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,105 @@
+// 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 log::{error, info};
+use nym_credential_storage::initialise_persistent_storage;
+use nym_credential_storage::models::StorableIssuedCredential;
+use nym_credential_storage::storage::Storage;
+use nym_credentials::coconut::bandwidth::issued::BandwidthCredentialIssuedDataVariant;
+use nym_credentials::IssuedBandwidthCredential;
+use std::fs;
+use std::path::PathBuf;
+use zeroize::Zeroizing;
+
+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, default_value_t = 1)]
+    pub(crate) version: 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 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())?
+        }
+    };
+    let raw_credential = Zeroizing::new(raw_credential);
+
+    // we're unpacking the data in order to make sure it's valid
+    // and to extract relevant metadata for storage purposes
+    let credential = match args.version {
+        1 => Zeroizing::new(IssuedBandwidthCredential::unpack_v1(&raw_credential)?),
+        other => panic!("unknown credential serialization version {other}"),
+    };
+    let persistent_storage = initialise_persistent_storage(credentials_store).await;
+
+    info!("importing {}", credential.typ());
+    match credential.variant_data() {
+        BandwidthCredentialIssuedDataVariant::Voucher(voucher_info) => {
+            info!("with value of {}", voucher_info.value())
+        }
+        BandwidthCredentialIssuedDataVariant::FreePass(freepass_info) => {
+            info!("with expiry at {}", freepass_info.expiry_date());
+            if freepass_info.expired() {
+                error!("the free pass has already expired!");
+
+                // technically we can, but the gateway will just reject it so what's the point
+                bail!("can't import an expired free pass")
+            }
+        }
+    }
+
+    let storable = StorableIssuedCredential {
+        serialization_revision: args.version,
+        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!"),
+    };
+
+    persistent_storage
+        .insert_issued_credential(storable)
+        .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/Cargo.toml

@@ -11,7 +11,9 @@ async-trait = { workspace = true }
 
 log = { workspace = true }
 thiserror = { workspace = true }
-tokio = { version = "1.24.1", features = ["sync"]}
+tokio = { workspace = true, features = ["sync"]}
+zeroize = { workspace = true, features = ["zeroize_derive"] }
+
 
 [target."cfg(not(target_arch = \"wasm32\"))".dependencies.sqlx]
 workspace = true

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

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+DROP TABLE coconut_credentials;
+CREATE TABLE coconut_credentials
+(
+    id                     INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+
+--     introduce a way for us to introduce breaking changes in serialization
+    serialization_revision INTEGER NOT NULL,
+    credential_type        TEXT    NOT NULL,
+    credential_data        BLOB    NOT NULL,
+    epoch_id               INTEGER NOT NULL,
+    consumed               BOOLEAN NOT NULL,
+    expired                BOOLEAN NOT NULL
+);

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

@@ -1,59 +1,65 @@
-// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2023-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::models::CoconutCredential;
+use crate::models::StoredIssuedCredential;
 use std::sync::Arc;
 use tokio::sync::RwLock;
 
 #[derive(Clone)]
 pub struct CoconutCredentialManager {
-    inner: Arc<RwLock<Vec<CoconutCredential>>>,
+    inner: Arc<RwLock<CoconutCredentialManagerInner>>,
+}
+
+#[derive(Default)]
+struct CoconutCredentialManagerInner {
+    data: Vec<StoredIssuedCredential>,
+    _next_id: i64,
+}
+
+impl CoconutCredentialManagerInner {
+    fn next_id(&mut self) -> i64 {
+        let next = self._next_id;
+        self._next_id += 1;
+        next
+    }
 }
 
 impl CoconutCredentialManager {
     /// Creates new empty instance of the `CoconutCredentialManager`.
     pub fn new() -> Self {
         CoconutCredentialManager {
-            inner: Arc::new(RwLock::new(Vec::new())),
+            inner: Default::default(),
         }
     }
 
-    /// Inserts provided signature into the database.
-    ///
-    /// # Arguments
-    ///
-    /// * `voucher_value`: Plaintext bandwidth value of the credential.
-    /// * `voucher_info`: Plaintext information of the credential.
-    /// * `serial_number`: Base58 representation of the serial number attribute.
-    /// * `binding_number`: Base58 representation of the binding number attribute.
-    /// * `signature`: Coconut credential in the form of a signature.
-    pub async fn insert_coconut_credential(
+    pub async fn insert_issued_credential(
         &self,
-        voucher_value: String,
-        voucher_info: String,
-        serial_number: String,
-        binding_number: String,
-        signature: String,
-        epoch_id: String,
+        credential_type: String,
+        serialization_revision: u8,
+        credential_data: &[u8],
+        epoch_id: u32,
     ) {
-        let mut creds = self.inner.write().await;
-        let id = creds.len() as i64;
-        creds.push(CoconutCredential {
+        let mut inner = self.inner.write().await;
+        let id = inner.next_id();
+        inner.data.push(StoredIssuedCredential {
             id,
-            voucher_value,
-            voucher_info,
-            serial_number,
-            binding_number,
-            signature,
+            serialization_revision,
+            credential_data: credential_data.to_vec(),
+            credential_type,
             epoch_id,
             consumed: false,
-        });
+            expired: false,
+        })
     }
 
     /// Tries to retrieve one of the stored, unused credentials.
-    pub async fn get_next_coconut_credential(&self) -> Option<CoconutCredential> {
+    pub async fn get_next_unspent_credential(&self) -> Option<StoredIssuedCredential> {
         let creds = self.inner.read().await;
-        creds.iter().find(|c| !c.consumed).cloned()
+        creds
+            .data
+            .iter()
+            .find(|c| !c.consumed && !c.expired)
+            .cloned()
     }
 
     /// Consumes in the database the specified credential.
@@ -63,8 +69,20 @@ impl CoconutCredentialManager {
     /// * `id`: Database id.
     pub async fn consume_coconut_credential(&self, id: i64) {
         let mut creds = self.inner.write().await;
-        if let Some(cred) = creds.get_mut(id as usize) {
+        if let Some(cred) = creds.data.get_mut(id as usize) {
             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

@@ -1,7 +1,7 @@
-// Copyright 2022 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2022-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::models::CoconutCredential;
+use crate::models::StoredIssuedCredential;
 
 #[derive(Clone)]
 pub struct CoconutCredentialManager {
@@ -18,40 +18,28 @@ impl CoconutCredentialManager {
         CoconutCredentialManager { connection_pool }
     }
 
-    /// Inserts provided signature into the database.
-    ///
-    /// # Arguments
-    ///
-    /// * `voucher_value`: Plaintext bandwidth value of the credential.
-    /// * `voucher_info`: Plaintext information of the credential.
-    /// * `serial_number`: Base58 representation of the serial number attribute.
-    /// * `binding_number`: Base58 representation of the binding number attribute.
-    /// * `signature`: Coconut credential in the form of a signature.
-    pub async fn insert_coconut_credential(
+    pub async fn insert_issued_credential(
         &self,
-        voucher_value: String,
-        voucher_info: String,
-        serial_number: String,
-        binding_number: String,
-        signature: String,
-        epoch_id: String,
+        credential_type: String,
+        serialization_revision: u8,
+        credential_data: &[u8],
+        epoch_id: u32,
     ) -> Result<(), sqlx::Error> {
         sqlx::query!(
-            "INSERT INTO coconut_credentials(voucher_value, voucher_info, serial_number, binding_number, signature, epoch_id, consumed) VALUES (?, ?, ?, ?, ?, ?, ?)",
-            voucher_value, voucher_info, serial_number, binding_number, signature, epoch_id, false
-        )
-        .execute(&self.connection_pool)
-        .await?;
+            r#"
+                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?;
         Ok(())
     }
 
-    /// Tries to retrieve one of the stored, unused credentials.
-    pub async fn get_next_coconut_credential(
+    pub async fn get_next_unspent_credential(
         &self,
-    ) -> Result<Option<CoconutCredential>, sqlx::Error> {
-        sqlx::query_as!(
-            CoconutCredential,
-            "SELECT * FROM coconut_credentials WHERE NOT consumed"
+    ) -> Result<Option<StoredIssuedCredential>, sqlx::Error> {
+        sqlx::query_as(
+            "SELECT * FROM coconut_credentials WHERE NOT consumed AND NOT expired LIMIT 1",
         )
         .fetch_optional(&self.connection_pool)
         .await
@@ -71,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

@@ -3,7 +3,7 @@
 
 use crate::backends::memory::CoconutCredentialManager;
 use crate::error::StorageError;
-use crate::models::CoconutCredential;
+use crate::models::{StorableIssuedCredential, StoredIssuedCredential};
 use crate::storage::Storage;
 use async_trait::async_trait;
 
@@ -27,37 +27,28 @@ impl Default for EphemeralStorage {
 impl Storage for EphemeralStorage {
     type StorageError = StorageError;
 
-    async fn insert_coconut_credential(
+    async fn insert_issued_credential<'a>(
         &self,
-        voucher_value: String,
-        voucher_info: String,
-        serial_number: String,
-        binding_number: String,
-        signature: String,
-        epoch_id: String,
+        bandwidth_credential: StorableIssuedCredential<'a>,
     ) -> Result<(), StorageError> {
         self.coconut_credential_manager
-            .insert_coconut_credential(
-                voucher_value,
-                voucher_info,
-                serial_number,
-                binding_number,
-                signature,
-                epoch_id,
+            .insert_issued_credential(
+                bandwidth_credential.credential_type,
+                bandwidth_credential.serialization_revision,
+                bandwidth_credential.credential_data,
+                bandwidth_credential.epoch_id,
             )
             .await;
-
         Ok(())
     }
 
-    async fn get_next_coconut_credential(&self) -> Result<CoconutCredential, StorageError> {
-        let credential = self
+    async fn get_next_unspent_credential(
+        &self,
+    ) -> Result<Option<StoredIssuedCredential>, Self::StorageError> {
+        Ok(self
             .coconut_credential_manager
-            .get_next_coconut_credential()
-            .await
-            .ok_or(StorageError::NoCredential)?;
-
-        Ok(credential)
+            .get_next_unspent_credential()
+            .await)
     }
 
     async fn consume_coconut_credential(&self, id: i64) -> Result<(), StorageError> {
@@ -67,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

@@ -1,15 +1,39 @@
-// Copyright 2022 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2022-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
-#[derive(Clone)]
-pub struct CoconutCredential {
-    #[allow(dead_code)]
+use zeroize::{Zeroize, ZeroizeOnDrop};
+
+// #[derive(Clone)]
+// pub struct CoconutCredential {
+//     #[allow(dead_code)]
+//     pub id: i64,
+//     pub voucher_value: String,
+//     pub voucher_info: String,
+//     pub serial_number: String,
+//     pub binding_number: String,
+//     pub signature: String,
+//     pub epoch_id: String,
+//     pub consumed: bool,
+// }
+
+#[cfg_attr(not(target_arch = "wasm32"), derive(sqlx::FromRow))]
+#[derive(Zeroize, ZeroizeOnDrop, Clone)]
+pub struct StoredIssuedCredential {
     pub id: i64,
-    pub voucher_value: String,
-    pub voucher_info: String,
-    pub serial_number: String,
-    pub binding_number: String,
-    pub signature: String,
-    pub epoch_id: String,
+
+    pub serialization_revision: u8,
+    pub credential_data: Vec<u8>,
+    pub credential_type: String,
+
+    pub epoch_id: u32,
     pub consumed: bool,
+    pub expired: bool,
+}
+
+pub struct StorableIssuedCredential<'a> {
+    pub serialization_revision: u8,
+    pub credential_data: &'a [u8],
+    pub credential_type: String,
+
+    pub epoch_id: u32,
 }

common/credential-storage/src/persistent_storage.rs

@@ -5,7 +5,7 @@ use crate::backends::sqlite::CoconutCredentialManager;
 use crate::error::StorageError;
 use crate::storage::Storage;
 
-use crate::models::CoconutCredential;
+use crate::models::{StorableIssuedCredential, StoredIssuedCredential};
 use async_trait::async_trait;
 use log::{debug, error};
 use sqlx::ConnectOptions;
@@ -58,37 +58,29 @@ impl PersistentStorage {
 impl Storage for PersistentStorage {
     type StorageError = StorageError;
 
-    async fn insert_coconut_credential(
+    async fn insert_issued_credential<'a>(
         &self,
-        voucher_value: String,
-        voucher_info: String,
-        serial_number: String,
-        binding_number: String,
-        signature: String,
-        epoch_id: String,
-    ) -> Result<(), StorageError> {
+        bandwidth_credential: StorableIssuedCredential<'a>,
+    ) -> Result<(), Self::StorageError> {
         self.coconut_credential_manager
-            .insert_coconut_credential(
-                voucher_value,
-                voucher_info,
-                serial_number,
-                binding_number,
-                signature,
-                epoch_id,
+            .insert_issued_credential(
+                bandwidth_credential.credential_type,
+                bandwidth_credential.serialization_revision,
+                bandwidth_credential.credential_data,
+                bandwidth_credential.epoch_id,
             )
             .await?;
 
         Ok(())
     }
 
-    async fn get_next_coconut_credential(&self) -> Result<CoconutCredential, StorageError> {
-        let credential = self
+    async fn get_next_unspent_credential(
+        &self,
+    ) -> Result<Option<StoredIssuedCredential>, Self::StorageError> {
+        Ok(self
             .coconut_credential_manager
-            .get_next_coconut_credential()
-            .await?
-            .ok_or(StorageError::NoCredential)?;
-
-        Ok(credential)
+            .get_next_unspent_credential()
+            .await?)
     }
 
     async fn consume_coconut_credential(&self, id: i64) -> Result<(), StorageError> {
@@ -98,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

@@ -1,7 +1,7 @@
 // Copyright 2022 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::models::CoconutCredential;
+use crate::models::{StorableIssuedCredential, StoredIssuedCredential};
 use async_trait::async_trait;
 use std::error::Error;
 
@@ -9,28 +9,16 @@ use std::error::Error;
 pub trait Storage: Send + Sync {
     type StorageError: Error;
 
-    /// Inserts provided signature into the database.
-    ///
-    /// # Arguments
-    ///
-    /// * `voucher_value`: How much bandwidth is in the credential.
-    /// * `voucher_info`: What type of credential it is.
-    /// * `serial_number`: Serial number of the credential.
-    /// * `binding_number`: Binding number of the credential.
-    /// * `signature`: Coconut credential in the form of a signature.
-    /// * `epoch_id`: The epoch when it was signed.
-    async fn insert_coconut_credential(
+    async fn insert_issued_credential<'a>(
         &self,
-        voucher_value: String,
-        voucher_info: String,
-        serial_number: String,
-        binding_number: String,
-        signature: String,
-        epoch_id: String,
+        bandwidth_credential: StorableIssuedCredential<'a>,
     ) -> Result<(), Self::StorageError>;
 
-    /// Tries to retrieve one of the stored, unused credentials.
-    async fn get_next_coconut_credential(&self) -> Result<CoconutCredential, Self::StorageError>;
+    /// Tries to retrieve one of the stored, unused credentials,
+    /// that is also not marked as expired
+    async fn get_next_unspent_credential(
+        &self,
+    ) -> Result<Option<StoredIssuedCredential>, Self::StorageError>;
 
     /// Marks as consumed in the database the specified credential.
     ///
@@ -38,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/Cargo.toml

@@ -12,6 +12,7 @@ thiserror = { workspace = true }
 tokio = { workspace = true }
 
 nym-bandwidth-controller = { path = "../../common/bandwidth-controller" }
+nym-coconut = { path = "../nymcoconut" }
 nym-credentials = { path = "../../common/credentials" }
 nym-credential-storage = { path = "../../common/credential-storage" }
 nym-validator-client = { path = "../../common/client-libs/validator-client" }

common/credential-utils/src/recovery_storage.rs

@@ -3,11 +3,13 @@
 
 use crate::errors::Result;
 use log::error;
-use nym_credentials::coconut::bandwidth::BandwidthVoucher;
+use nym_credentials::coconut::bandwidth::IssuanceBandwidthCredential;
 use std::fs::{create_dir_all, read_dir, File};
 use std::io::{Read, Write};
 use std::path::PathBuf;
 
+pub const DUMPED_VOUCHER_EXTENSION: &str = "credentialrecovery";
+
 pub struct RecoveryStorage {
     recovery_dir: PathBuf,
 }
@@ -18,14 +20,16 @@ impl RecoveryStorage {
         Ok(Self { recovery_dir })
     }
 
-    pub fn unconsumed_vouchers(&self) -> Result<Vec<BandwidthVoucher>> {
+    pub fn unconsumed_vouchers(&self) -> Result<Vec<IssuanceBandwidthCredential>> {
         let entries = read_dir(&self.recovery_dir)?;
 
         let mut paths = vec![];
         for entry in entries.flatten() {
             let path = entry.path();
-            if path.is_file() {
-                paths.push(path)
+            if let Some(extension) = path.extension() {
+                if extension == DUMPED_VOUCHER_EXTENSION {
+                    paths.push(path)
+                }
             }
         }
 
@@ -34,7 +38,7 @@ impl RecoveryStorage {
             if let Ok(mut file) = File::open(&path) {
                 let mut buff = Vec::new();
                 if file.read_to_end(&mut buff).is_ok() {
-                    match BandwidthVoucher::try_from_bytes(&buff) {
+                    match IssuanceBandwidthCredential::try_from_recovered_bytes(&buff) {
                         Ok(voucher) => vouchers.push(voucher),
                         Err(err) => {
                             error!("failed to parse the voucher at {}: {err}", path.display())
@@ -47,11 +51,17 @@ impl RecoveryStorage {
         Ok(vouchers)
     }
 
-    pub fn insert_voucher(&self, voucher: &BandwidthVoucher) -> Result<PathBuf> {
-        let file_name = voucher.tx_hash().to_string();
+    pub fn voucher_filename(voucher: &IssuanceBandwidthCredential) -> String {
+        let prefix = voucher.typ().to_string();
+        let suffix = voucher.blinded_serial_number_bs58();
+        format!("{prefix}-{suffix}.{DUMPED_VOUCHER_EXTENSION}")
+    }
+
+    pub fn insert_voucher(&self, voucher: &IssuanceBandwidthCredential) -> Result<PathBuf> {
+        let file_name = Self::voucher_filename(voucher);
         let file_path = self.recovery_dir.join(file_name);
         let mut file = File::create(&file_path)?;
-        let buff = voucher.to_bytes();
+        let buff = voucher.to_recovery_bytes();
         file.write_all(&buff)?;
 
         Ok(file_path)

common/credential-utils/src/utils.rs

@@ -5,6 +5,7 @@ use nym_bandwidth_controller::acquire::state::State;
 use nym_client_core::config::disk_persistence::CommonClientPaths;
 use nym_config::DEFAULT_DATA_DIR;
 use nym_credential_storage::persistent_storage::PersistentStorage;
+use nym_credentials::coconut::bandwidth::CredentialType;
 use nym_validator_client::nyxd::contract_traits::{
     dkg_query_client::EpochState, CoconutBandwidthSigningClient, DkgQueryClient,
 };
@@ -43,7 +44,7 @@ where
 
     let state = nym_bandwidth_controller::acquire::deposit(client, amount.clone()).await?;
 
-    if nym_bandwidth_controller::acquire::get_credential(&state, client, persistent_storage)
+    if nym_bandwidth_controller::acquire::get_bandwidth_voucher(&state, client, persistent_storage)
         .await
         .is_err()
     {
@@ -91,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);
@@ -128,19 +129,29 @@ where
 {
     let mut recovered_amount: u128 = 0;
     for voucher in recovery_storage.unconsumed_vouchers()? {
-        let voucher_value = voucher.get_voucher_value();
+        let voucher_value = match voucher.typ() {
+            CredentialType::Voucher => voucher.get_bandwidth_attribute(),
+            CredentialType::FreePass => {
+                error!("unimplemented recovery of free pass credentials");
+                continue;
+            }
+        };
         recovered_amount += voucher_value.parse::<u128>()?;
 
+        let voucher_name = RecoveryStorage::voucher_filename(&voucher);
         let state = State::new(voucher);
-        let voucher = state.voucher.tx_hash();
+
         if let Err(e) =
-            nym_bandwidth_controller::acquire::get_credential(&state, client, shared_storage).await
+            nym_bandwidth_controller::acquire::get_bandwidth_voucher(&state, client, shared_storage)
+                .await
         {
-            error!("Could not recover deposit {voucher} due to {e}, try again later",)
+            error!("Could not recover deposit {voucher_name} due to {e}, try again later",)
         } else {
-            info!("Converted deposit {voucher} to a credential, removing recovery data for it",);
-            if let Err(e) = recovery_storage.remove_voucher(voucher.to_string()) {
-                warn!("Could not remove recovery data: {e}");
+            info!(
+                "Converted deposit {voucher_name} to a credential, removing recovery data for it",
+            );
+            if let Err(err) = recovery_storage.remove_voucher(voucher_name) {
+                warn!("Could not remove recovery data: {err}");
             }
         }
     }

common/credentials-interface/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "nym-credentials-interface"
+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]
+bls12_381 = { workspace = true, default-features = false }
+serde = { workspace = true, features = ["derive"] }
+thiserror = { workspace = true }
+
+nym-coconut = { path = "../nymcoconut" }

common/credentials-interface/src/lib.rs

@@ -0,0 +1,136 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use bls12_381::Scalar;
+use serde::{Deserialize, Serialize};
+use std::fmt::{Display, Formatter};
+use std::str::FromStr;
+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, BlindedSerialNumber, BlindedSignature, Bytable, CoconutError, KeyPair,
+    Parameters, PrivateAttribute, PublicAttribute, SecretKey, Signature, SignatureShare,
+    VerificationKey, VerifyCredentialRequest,
+};
+
+pub const VOUCHER_INFO_TYPE: &str = "BandwidthVoucher";
+pub const FREE_PASS_INFO_TYPE: &str = "FreeBandwidthPass";
+
+// pub trait NymCredential {
+//     fn prove_credential(&self) -> Result<(), ()>;
+// }
+
+#[derive(Debug, Error)]
+#[error("{0} is not a valid credential type")]
+pub struct UnknownCredentialType(String);
+
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)]
+pub enum CredentialType {
+    Voucher,
+    FreePass,
+}
+
+impl FromStr for CredentialType {
+    type Err = UnknownCredentialType;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        if s == VOUCHER_INFO_TYPE {
+            Ok(CredentialType::Voucher)
+        } else if s == FREE_PASS_INFO_TYPE {
+            Ok(CredentialType::FreePass)
+        } else {
+            Err(UnknownCredentialType(s.to_string()))
+        }
+    }
+}
+
+impl CredentialType {
+    pub fn validate(&self, type_plain: &str) -> bool {
+        match self {
+            CredentialType::Voucher => type_plain == VOUCHER_INFO_TYPE,
+            CredentialType::FreePass => type_plain == FREE_PASS_INFO_TYPE,
+        }
+    }
+
+    pub fn is_free_pass(&self) -> bool {
+        matches!(self, CredentialType::FreePass)
+    }
+
+    pub fn is_voucher(&self) -> bool {
+        matches!(self, CredentialType::Voucher)
+    }
+}
+
+impl Display for CredentialType {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            CredentialType::Voucher => VOUCHER_INFO_TYPE.fmt(f),
+            CredentialType::FreePass => FREE_PASS_INFO_TYPE.fmt(f),
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct CredentialSigningData {
+    pub pedersen_commitments_openings: Vec<Scalar>,
+
+    pub blind_sign_request: BlindSignRequest,
+
+    pub public_attributes_plain: Vec<String>,
+
+    pub typ: CredentialType,
+}
+
+#[derive(Debug, Serialize, Deserialize, PartialEq, Eq, Clone)]
+pub struct CredentialSpendingData {
+    pub embedded_private_attributes: usize,
+
+    pub verify_credential_request: VerifyCredentialRequest,
+
+    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 {
+    pub fn verify(&self, params: &Parameters, verification_key: &VerificationKey) -> bool {
+        let hashed_public_attributes = self
+            .public_attributes_plain
+            .iter()
+            .map(hash_to_scalar)
+            .collect::<Vec<_>>();
+
+        // get references to the attributes
+        let public_attributes = hashed_public_attributes.iter().collect::<Vec<_>>();
+
+        verify_credential(
+            params,
+            verification_key,
+            &self.verify_credential_request,
+            &public_attributes,
+        )
+    }
+
+    pub fn validate_type_attribute(&self) -> bool {
+        // the first attribute is variant specific bandwidth encoding, the second one should be the type
+        let Some(type_plain) = self.public_attributes_plain.get(1) else {
+            return false;
+        };
+
+        self.typ.validate(type_plain)
+    }
+
+    pub fn get_bandwidth_attribute(&self) -> Option<&String> {
+        // 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/Cargo.toml

@@ -8,14 +8,17 @@ license.workspace = true
 
 [dependencies]
 bls12_381 = { workspace = true, default-features = false, features = ["pairings", "alloc", "experimental"] }
+bincode = "1.3.3"
 cosmrs = { workspace = true }
 thiserror = { workspace = true }
 log = { workspace = true }
+time = { workspace = true, features = ["serde"] }
+serde = { workspace = true, features = ["derive"] }
 zeroize = { workspace = true }
 
 # I guess temporarily until we get serde support in coconut up and running
-nym-coconut-interface = { path = "../coconut-interface" }
-nym-crypto = { path = "../crypto", features = ["rand", "asymmetric"] }
+nym-credentials-interface = { path = "../credentials-interface" }
+nym-crypto = { path = "../crypto", features = ["rand", "asymmetric", "serde"] }
 nym-api-requests = { path = "../../nym-api/nym-api-requests" }
 nym-validator-client = { path = "../client-libs/validator-client", default-features = false }
 

common/credentials/src/coconut/bandwidth.rs

@@ -1,428 +0,0 @@
-// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
-// SPDX-License-Identifier: Apache-2.0
-
-// for time being assume the bandwidth credential consists of public identity of the requester
-// and private (though known... just go along with it) infinite bandwidth value
-// right now this has no double-spending protection, spender binding, etc
-// it's the simplest possible case
-
-use cosmrs::tendermint::hash::Algorithm;
-use cosmrs::tendermint::Hash;
-use nym_coconut_interface::{
-    hash_to_scalar, prepare_blind_sign, Attribute, BlindSignRequest, Credential, Parameters,
-    PrivateAttribute, PublicAttribute, Signature, VerificationKey,
-};
-use nym_crypto::asymmetric::{encryption, identity};
-use zeroize::{Zeroize, ZeroizeOnDrop};
-
-use super::utils::prepare_credential_for_spending;
-use crate::error::Error;
-
-#[derive(Zeroize, ZeroizeOnDrop)]
-pub struct BandwidthVoucher {
-    // private attributes
-    /// a random secret value generated by the client used for double-spending detection
-    serial_number: PrivateAttribute,
-
-    /// a random secret value generated by the client used to bind multiple credentials together
-    binding_number: PrivateAttribute,
-
-    // public atttributes:
-    /// the plain text value (e.g., bandwidth) encoded in this voucher
-    // TODO: in another PR change the value from `"1000"` to `"1000unym"`
-    voucher_value_plain: String,
-
-    /// the plain text information
-    voucher_info_plain: String,
-
-    /// the precomputed value (e.g., bandwidth) encoded in this voucher
-    _voucher_value_prehashed: PublicAttribute,
-
-    /// the precomputed field with public information, e.g., type of voucher, interval etc.
-    _voucher_info_prehashed: PublicAttribute,
-
-    /// the hash of the deposit transaction
-    #[zeroize(skip)]
-    tx_hash: Hash,
-
-    /// base58 encoded private key ensuring the depositer requested these attributes
-    signing_key: identity::PrivateKey,
-
-    /// base58 encoded private key ensuring only this client receives the signature share
-    unused_ed25519: encryption::PrivateKey,
-
-    pedersen_commitments_openings: Vec<Attribute>,
-
-    #[zeroize(skip)]
-    blind_sign_request: BlindSignRequest,
-}
-
-impl BandwidthVoucher {
-    pub const PUBLIC_ATTRIBUTES: u32 = 2;
-    pub const PRIVATE_ATTRIBUTES: u32 = 2;
-    pub const ENCODED_ATTRIBUTES: u32 = 4;
-
-    pub fn default_parameters() -> Parameters {
-        // safety: the unwrap is fine here as Self::ENCODED_ATTRIBUTES is non-zero
-        Parameters::new(Self::ENCODED_ATTRIBUTES).unwrap()
-    }
-
-    pub fn new(
-        params: &Parameters,
-        voucher_value: String,
-        voucher_info: String,
-        tx_hash: Hash,
-        signing_key: identity::PrivateKey,
-        encryption_key: encryption::PrivateKey,
-    ) -> Self {
-        let serial_number = params.random_scalar();
-        let binding_number = params.random_scalar();
-        let voucher_value_plain = voucher_value.clone();
-        let voucher_info_plain = voucher_info.clone();
-
-        let _voucher_value_prehashed = hash_to_scalar(voucher_value);
-        let _voucher_info_prehashed = hash_to_scalar(voucher_info);
-
-        let (pedersen_commitments_openings, blind_sign_request) = prepare_blind_sign(
-            params,
-            &[&serial_number, &binding_number],
-            &[&_voucher_value_prehashed, &_voucher_info_prehashed],
-        )
-        .unwrap();
-        BandwidthVoucher {
-            serial_number,
-            binding_number,
-            _voucher_value_prehashed,
-            voucher_value_plain,
-            _voucher_info_prehashed,
-            voucher_info_plain,
-            tx_hash,
-            signing_key,
-            unused_ed25519: encryption_key,
-            pedersen_commitments_openings,
-            blind_sign_request,
-        }
-    }
-
-    pub fn to_bytes(&self) -> Vec<u8> {
-        let serial_number_b = self.serial_number.to_bytes();
-        let binding_number_b = self.binding_number.to_bytes();
-        let voucher_value_plain_b = self.voucher_value_plain.as_bytes();
-        let voucher_info_plain_b = self.voucher_info_plain.as_bytes();
-        let tx_hash_b = self.tx_hash.as_bytes();
-        let signing_key_b = self.signing_key.to_bytes();
-        let encryption_key_b = self.unused_ed25519.to_bytes();
-        let blind_sign_request_b = self.blind_sign_request.to_bytes();
-
-        let mut ret = Vec::new();
-
-        ret.extend_from_slice(&serial_number_b);
-        ret.extend_from_slice(&binding_number_b);
-        ret.extend_from_slice(tx_hash_b);
-        ret.extend_from_slice(&signing_key_b);
-        ret.extend_from_slice(&encryption_key_b);
-        ret.extend_from_slice(&(voucher_value_plain_b.len() as u64).to_be_bytes());
-        ret.extend_from_slice(&(voucher_info_plain_b.len() as u64).to_be_bytes());
-        ret.extend_from_slice(&(blind_sign_request_b.len() as u64).to_be_bytes());
-        ret.extend_from_slice(&(self.pedersen_commitments_openings.len() as u64).to_be_bytes());
-        ret.extend_from_slice(voucher_value_plain_b);
-        ret.extend_from_slice(voucher_info_plain_b);
-        ret.extend_from_slice(&blind_sign_request_b);
-        for commitment in self.pedersen_commitments_openings.iter() {
-            ret.extend_from_slice(&commitment.to_bytes());
-        }
-
-        ret
-    }
-
-    pub fn try_from_bytes(bytes: &[u8]) -> Result<Self, Error> {
-        if bytes.len() < 32 * 5 + 4 * 8 {
-            return Err(Error::BandwidthVoucherDeserializationError(format!(
-                "Less then {} bytes needed",
-                32 * 5 + 4 * 8
-            )));
-        }
-        let mut buff = [0u8; 32];
-        let mut small_buff = [0u8; 8];
-        let scalar_err =
-            || Error::BandwidthVoucherDeserializationError(String::from("Invalid Scalar"));
-        buff.copy_from_slice(&bytes[..32]);
-        let serial_number = Option::<PrivateAttribute>::from(PrivateAttribute::from_bytes(&buff))
-            .ok_or_else(scalar_err)?;
-        buff.copy_from_slice(&bytes[32..2 * 32]);
-        let binding_number = Option::<PrivateAttribute>::from(PrivateAttribute::from_bytes(&buff))
-            .ok_or_else(scalar_err)?;
-        buff.copy_from_slice(&bytes[2 * 32..3 * 32]);
-        let tx_hash = Hash::from_bytes(Algorithm::Sha256, &buff).map_err(|_| {
-            Error::BandwidthVoucherDeserializationError(String::from("Invalid transaction Hash"))
-        })?;
-        buff.copy_from_slice(&bytes[3 * 32..4 * 32]);
-        let signing_key = identity::PrivateKey::from_bytes(&buff).map_err(|_| {
-            Error::BandwidthVoucherDeserializationError(String::from("Invalid key"))
-        })?;
-        buff.copy_from_slice(&bytes[4 * 32..5 * 32]);
-        let encryption_key = encryption::PrivateKey::from_bytes(&buff).map_err(|_| {
-            Error::BandwidthVoucherDeserializationError(String::from("Invalid key"))
-        })?;
-        small_buff.copy_from_slice(&bytes[5 * 32..5 * 32 + 8]);
-        let voucher_value_plain_no = u64::from_be_bytes(small_buff) as usize;
-        small_buff.copy_from_slice(&bytes[5 * 32 + 8..5 * 32 + 2 * 8]);
-        let voucher_info_plain_no = u64::from_be_bytes(small_buff) as usize;
-        small_buff.copy_from_slice(&bytes[5 * 32 + 2 * 8..5 * 32 + 3 * 8]);
-        let blind_sign_request_no = u64::from_be_bytes(small_buff) as usize;
-        small_buff.copy_from_slice(&bytes[5 * 32 + 3 * 8..5 * 32 + 4 * 8]);
-        let pedersen_commitments_openings_no = u64::from_be_bytes(small_buff) as usize;
-
-        let total_length = 32 * 5
-            + 4 * 8
-            + voucher_value_plain_no
-            + voucher_info_plain_no
-            + blind_sign_request_no
-            + pedersen_commitments_openings_no * 32;
-        if bytes.len() != total_length {
-            return Err(Error::BandwidthVoucherDeserializationError(format!(
-                "Expected {total_length} bytes",
-            )));
-        }
-
-        let utf_err = |_| {
-            Err(Error::BandwidthVoucherDeserializationError(String::from(
-                "Invalid UTF8 string",
-            )))
-        };
-        let mut var_length_pointer = 5 * 32 + 4 * 8;
-        let voucher_value_plain = String::from_utf8(
-            bytes[var_length_pointer..var_length_pointer + voucher_value_plain_no].to_vec(),
-        )
-        .or_else(utf_err)?;
-        let _voucher_value_prehashed = hash_to_scalar(&voucher_value_plain);
-        var_length_pointer += voucher_value_plain_no;
-        let voucher_info_plain = String::from_utf8(
-            bytes[var_length_pointer..var_length_pointer + voucher_info_plain_no].to_vec(),
-        )
-        .or_else(utf_err)?;
-        let _voucher_info_prehashed = hash_to_scalar(&voucher_info_plain);
-        var_length_pointer += voucher_info_plain_no;
-        let blind_sign_request = BlindSignRequest::from_bytes(
-            &bytes[var_length_pointer..var_length_pointer + blind_sign_request_no],
-        )?;
-        var_length_pointer += blind_sign_request_no;
-
-        let mut pedersen_commitments_openings = Vec::new();
-        for _ in 0..pedersen_commitments_openings_no {
-            buff.copy_from_slice(&bytes[var_length_pointer..var_length_pointer + 32]);
-            let commitment =
-                Option::<Attribute>::from(Attribute::from_bytes(&buff)).ok_or_else(scalar_err)?;
-            var_length_pointer += 32;
-            pedersen_commitments_openings.push(commitment);
-        }
-
-        Ok(Self {
-            serial_number,
-            binding_number,
-            _voucher_value_prehashed,
-            voucher_value_plain,
-            _voucher_info_prehashed,
-            voucher_info_plain,
-            tx_hash,
-            signing_key,
-            unused_ed25519: encryption_key,
-            pedersen_commitments_openings,
-            blind_sign_request,
-        })
-    }
-
-    /// Check if the plain values correspond to the PublicAttributes
-    pub fn verify_against_plain(values: &[&PublicAttribute], plain_values: &[String]) -> bool {
-        values.len() == 2
-            && plain_values.len() == 2
-            && values[0] == &hash_to_scalar(&plain_values[0])
-            && values[1] == &hash_to_scalar(&plain_values[1])
-    }
-
-    pub fn tx_hash(&self) -> Hash {
-        self.tx_hash
-    }
-
-    pub fn get_public_attributes(&self) -> Vec<&PublicAttribute> {
-        vec![
-            &self._voucher_value_prehashed,
-            &self._voucher_info_prehashed,
-        ]
-    }
-
-    pub fn identity_key(&self) -> &identity::PrivateKey {
-        &self.signing_key
-    }
-
-    pub fn encryption_key(&self) -> &encryption::PrivateKey {
-        &self.unused_ed25519
-    }
-
-    pub fn pedersen_commitments_openings(&self) -> &Vec<Attribute> {
-        &self.pedersen_commitments_openings
-    }
-
-    pub fn blind_sign_request(&self) -> &BlindSignRequest {
-        &self.blind_sign_request
-    }
-
-    pub fn get_voucher_value(&self) -> String {
-        self.voucher_value_plain.clone()
-    }
-
-    pub fn get_public_attributes_plain(&self) -> Vec<String> {
-        vec![
-            self.voucher_value_plain.clone(),
-            self.voucher_info_plain.clone(),
-        ]
-    }
-
-    pub fn get_private_attributes(&self) -> Vec<&PrivateAttribute> {
-        vec![&self.serial_number, &self.binding_number]
-    }
-
-    pub fn signable_plaintext(request: &BlindSignRequest, tx_hash: Hash) -> Vec<u8> {
-        let mut message = request.to_bytes();
-        message.extend_from_slice(tx_hash.as_bytes());
-        message
-    }
-
-    pub fn sign(&self) -> identity::Signature {
-        let message = Self::signable_plaintext(&self.blind_sign_request, self.tx_hash);
-        self.signing_key.sign(message)
-    }
-}
-
-pub fn prepare_for_spending(
-    voucher_value: u64,
-    voucher_info: String,
-    serial_number: &PrivateAttribute,
-    binding_number: &PrivateAttribute,
-    epoch_id: u64,
-    signature: &Signature,
-    verification_key: &VerificationKey,
-) -> Result<Credential, Error> {
-    let params = Parameters::new(BandwidthVoucher::ENCODED_ATTRIBUTES)?;
-
-    prepare_credential_for_spending(
-        &params,
-        voucher_value,
-        voucher_info,
-        serial_number,
-        binding_number,
-        epoch_id,
-        signature,
-        verification_key,
-    )
-}
-
-#[cfg(test)]
-mod test {
-    use super::*;
-    use cosmrs::tendermint::hash::Algorithm;
-    use nym_coconut_interface::Base58;
-    use rand::rngs::OsRng;
-
-    fn voucher_fixture() -> BandwidthVoucher {
-        let params = Parameters::new(4).unwrap();
-        let mut rng = OsRng;
-        BandwidthVoucher::new(
-            &params,
-            "1234".to_string(),
-            "voucher info".to_string(),
-            Hash::from_bytes(Algorithm::Sha256, &[0; 32]).unwrap(),
-            identity::PrivateKey::from_base58_string(
-                identity::KeyPair::new(&mut rng)
-                    .private_key()
-                    .to_base58_string(),
-            )
-            .unwrap(),
-            encryption::PrivateKey::from_bytes(
-                &encryption::KeyPair::new(&mut rng).private_key().to_bytes(),
-            )
-            .unwrap(),
-        )
-    }
-
-    #[test]
-    fn serde_voucher() {
-        let voucher = voucher_fixture();
-        let bytes = voucher.to_bytes();
-        let deserialized_voucher = BandwidthVoucher::try_from_bytes(&bytes).unwrap();
-        assert_eq!(voucher.serial_number, deserialized_voucher.serial_number);
-        assert_eq!(voucher.binding_number, deserialized_voucher.binding_number);
-        assert_eq!(
-            voucher.voucher_value_plain,
-            deserialized_voucher.voucher_value_plain
-        );
-        assert_eq!(
-            voucher.voucher_info_plain,
-            deserialized_voucher.voucher_info_plain
-        );
-        assert_eq!(
-            voucher._voucher_value_prehashed,
-            deserialized_voucher._voucher_value_prehashed
-        );
-        assert_eq!(
-            voucher._voucher_info_prehashed,
-            deserialized_voucher._voucher_info_prehashed
-        );
-        assert_eq!(voucher.tx_hash, deserialized_voucher.tx_hash);
-        assert_eq!(
-            voucher.signing_key.to_string(),
-            deserialized_voucher.signing_key.to_string()
-        );
-        assert_eq!(
-            voucher.unused_ed25519.to_string(),
-            deserialized_voucher.unused_ed25519.to_string()
-        );
-        assert_eq!(
-            voucher.pedersen_commitments_openings,
-            deserialized_voucher.pedersen_commitments_openings
-        );
-        assert_eq!(
-            voucher.blind_sign_request.to_bs58(),
-            deserialized_voucher.blind_sign_request.to_bs58()
-        );
-    }
-
-    #[test]
-    fn voucher_consistency() {
-        let voucher = voucher_fixture();
-        assert!(!BandwidthVoucher::verify_against_plain(
-            &[],
-            &voucher.get_public_attributes_plain()
-        ));
-        assert!(!BandwidthVoucher::verify_against_plain(
-            &voucher.get_public_attributes(),
-            &[],
-        ));
-        assert!(!BandwidthVoucher::verify_against_plain(
-            &voucher.get_public_attributes(),
-            &[
-                voucher.get_public_attributes_plain()[0].clone(),
-                String::new()
-            ]
-        ));
-        assert!(!BandwidthVoucher::verify_against_plain(
-            &voucher.get_public_attributes(),
-            &[
-                String::new(),
-                voucher.get_public_attributes_plain()[1].clone()
-            ]
-        ));
-        assert!(!BandwidthVoucher::verify_against_plain(
-            &[voucher.get_public_attributes()[0], &Attribute::one()],
-            &voucher.get_public_attributes_plain()
-        ));
-        assert!(!BandwidthVoucher::verify_against_plain(
-            &[&Attribute::one(), voucher.get_public_attributes()[1]],
-            &voucher.get_public_attributes_plain()
-        ));
-        assert!(BandwidthVoucher::verify_against_plain(
-            &voucher.get_public_attributes(),
-            &voucher.get_public_attributes_plain()
-        ));
-    }
-}

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

@@ -0,0 +1,141 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::coconut::utils::scalar_serde_helper;
+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(Debug, Zeroize, ZeroizeOnDrop, Serialize, Deserialize)]
+pub struct FreePassIssuedData {
+    /// the plain validity value of this credential expressed as unix timestamp
+    #[zeroize(skip)]
+    expiry_date: OffsetDateTime,
+}
+
+impl<'a> From<&'a FreePassIssuanceData> for FreePassIssuedData {
+    fn from(value: &'a FreePassIssuanceData) -> Self {
+        FreePassIssuedData {
+            expiry_date: value.expiry_date,
+        }
+    }
+}
+
+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()
+    }
+}
+
+#[derive(Zeroize, Serialize, Deserialize)]
+pub struct FreePassIssuanceData {
+    /// the plain validity value of this credential expressed as unix timestamp
+    #[zeroize(skip)]
+    expiry_date: OffsetDateTime,
+
+    // the expiry date, as unix timestamp, hashed into a scalar
+    #[serde(with = "scalar_serde_helper")]
+    expiry_date_prehashed: PublicAttribute,
+}
+
+impl FreePassIssuanceData {
+    pub fn new(expiry_date: Option<OffsetDateTime>) -> Self {
+        // ideally we should have implemented a proper error handling here, sure.
+        // but given it's meant to only be used by nym, imo it's fine to just panic here in case of invalid arguments
+        let expiry_date = if let Some(provided) = expiry_date {
+            if provided - OffsetDateTime::now_utc() > MAX_FREE_PASS_VALIDITY {
+                panic!("the provided expiry date is bigger than the maximum value of {MAX_FREE_PASS_VALIDITY}");
+            }
+
+            provided
+        } else {
+            Self::default_expiry_date()
+        };
+
+        let expiry_date_prehashed = hash_to_scalar(expiry_date.unix_timestamp().to_string());
+
+        FreePassIssuanceData {
+            expiry_date,
+            expiry_date_prehashed,
+        }
+    }
+
+    pub fn default_expiry_date() -> OffsetDateTime {
+        // set it to furthest midnight in the future such as it's no more than a week away,
+        // i.e. if it's currently for example 9:43 on 2nd March 2024, it will set it to 0:00 on 9th March 2024
+        (OffsetDateTime::now_utc() + MAX_FREE_PASS_VALIDITY).replace_time(Time::MIDNIGHT)
+    }
+
+    pub fn expiry_date_attribute(&self) -> &Attribute {
+        &self.expiry_date_prehashed
+    }
+
+    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

@@ -0,0 +1,329 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::coconut::bandwidth::freepass::FreePassIssuanceData;
+use crate::coconut::bandwidth::issued::IssuedBandwidthCredential;
+use crate::coconut::bandwidth::voucher::BandwidthVoucherIssuanceData;
+use crate::coconut::bandwidth::{
+    bandwidth_credential_params, CredentialSigningData, CredentialType,
+};
+use crate::coconut::utils::scalar_serde_helper;
+use crate::error::Error;
+use nym_credentials_interface::{
+    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};
+
+#[derive(Zeroize, ZeroizeOnDrop, Serialize, Deserialize)]
+pub enum BandwidthCredentialIssuanceDataVariant {
+    Voucher(BandwidthVoucherIssuanceData),
+    FreePass(FreePassIssuanceData),
+}
+
+impl From<FreePassIssuanceData> for BandwidthCredentialIssuanceDataVariant {
+    fn from(value: FreePassIssuanceData) -> Self {
+        BandwidthCredentialIssuanceDataVariant::FreePass(value)
+    }
+}
+
+impl From<BandwidthVoucherIssuanceData> for BandwidthCredentialIssuanceDataVariant {
+    fn from(value: BandwidthVoucherIssuanceData) -> Self {
+        BandwidthCredentialIssuanceDataVariant::Voucher(value)
+    }
+}
+
+impl BandwidthCredentialIssuanceDataVariant {
+    pub fn info(&self) -> CredentialType {
+        match self {
+            BandwidthCredentialIssuanceDataVariant::Voucher(..) => CredentialType::Voucher,
+            BandwidthCredentialIssuanceDataVariant::FreePass(..) => CredentialType::FreePass,
+        }
+    }
+
+    // currently this works under the assumption of there being a single unique public attribute for given variant
+    pub fn public_value(&self) -> &Attribute {
+        match self {
+            BandwidthCredentialIssuanceDataVariant::Voucher(voucher) => voucher.value_attribute(),
+            BandwidthCredentialIssuanceDataVariant::FreePass(freepass) => {
+                freepass.expiry_date_attribute()
+            }
+        }
+    }
+
+    // currently this works under the assumption of there being a single unique public attribute for given variant
+    pub fn public_value_plain(&self) -> String {
+        match self {
+            BandwidthCredentialIssuanceDataVariant::Voucher(voucher) => voucher.value_plain(),
+            BandwidthCredentialIssuanceDataVariant::FreePass(freepass) => {
+                freepass.expiry_date_plain()
+            }
+        }
+    }
+
+    pub fn voucher_data(&self) -> Option<&BandwidthVoucherIssuanceData> {
+        match self {
+            BandwidthCredentialIssuanceDataVariant::Voucher(voucher) => Some(voucher),
+            _ => None,
+        }
+    }
+}
+
+// all types of bandwidth credentials contain serial number and binding number
+#[derive(Zeroize, ZeroizeOnDrop, Serialize, Deserialize)]
+pub struct IssuanceBandwidthCredential {
+    // private attributes
+    /// a random secret value generated by the client used for double-spending detection
+    #[serde(with = "scalar_serde_helper")]
+    serial_number: PrivateAttribute,
+
+    /// a random secret value generated by the client used to bind multiple credentials together
+    #[serde(with = "scalar_serde_helper")]
+    binding_number: PrivateAttribute,
+
+    /// data specific to given bandwidth credential, for example a value for bandwidth voucher and expiry date for the free pass
+    variant_data: BandwidthCredentialIssuanceDataVariant,
+
+    /// type of the bandwdith credential hashed onto a scalar
+    #[serde(with = "scalar_serde_helper")]
+    type_prehashed: PublicAttribute,
+}
+
+impl IssuanceBandwidthCredential {
+    pub const PUBLIC_ATTRIBUTES: u32 = 2;
+    pub const PRIVATE_ATTRIBUTES: u32 = 2;
+    pub const ENCODED_ATTRIBUTES: u32 = Self::PUBLIC_ATTRIBUTES + Self::PRIVATE_ATTRIBUTES;
+
+    pub fn default_parameters() -> Parameters {
+        // safety: the unwrap is fine here as Self::ENCODED_ATTRIBUTES is non-zero
+        Parameters::new(Self::ENCODED_ATTRIBUTES).unwrap()
+    }
+
+    pub fn new<B: Into<BandwidthCredentialIssuanceDataVariant>>(variant_data: B) -> Self {
+        let variant_data = variant_data.into();
+        let type_prehashed = hash_to_scalar(variant_data.info().to_string());
+
+        let params = bandwidth_credential_params();
+        let serial_number = params.random_scalar();
+        let binding_number = params.random_scalar();
+
+        IssuanceBandwidthCredential {
+            serial_number,
+            binding_number,
+            variant_data,
+            type_prehashed,
+        }
+    }
+
+    pub fn new_voucher(
+        value: impl Into<Coin>,
+        deposit_tx_hash: Hash,
+        signing_key: identity::PrivateKey,
+        unused_ed25519: encryption::PrivateKey,
+    ) -> Self {
+        Self::new(BandwidthVoucherIssuanceData::new(
+            value,
+            deposit_tx_hash,
+            signing_key,
+            unused_ed25519,
+        ))
+    }
+
+    pub fn new_freepass(expiry_date: Option<OffsetDateTime>) -> Self {
+        Self::new(FreePassIssuanceData::new(expiry_date))
+    }
+
+    pub fn blind_serial_number(&self) -> BlindedSerialNumber {
+        (bandwidth_credential_params().gen2() * self.serial_number).into()
+    }
+
+    pub fn blinded_serial_number_bs58(&self) -> String {
+        use nym_credentials_interface::Base58;
+
+        self.blind_serial_number().to_bs58()
+    }
+
+    pub fn typ(&self) -> CredentialType {
+        self.variant_data.info()
+    }
+
+    pub fn get_private_attributes(&self) -> Vec<&PrivateAttribute> {
+        vec![&self.serial_number, &self.binding_number]
+    }
+
+    pub fn get_public_attributes(&self) -> Vec<&PublicAttribute> {
+        vec![self.variant_data.public_value(), &self.type_prehashed]
+    }
+
+    pub fn get_plain_public_attributes(&self) -> Vec<String> {
+        vec![
+            self.variant_data.public_value_plain(),
+            self.typ().to_string(),
+        ]
+    }
+
+    pub fn get_variant_data(&self) -> &BandwidthCredentialIssuanceDataVariant {
+        &self.variant_data
+    }
+
+    pub fn get_bandwidth_attribute(&self) -> String {
+        self.variant_data.public_value_plain()
+    }
+
+    pub fn prepare_for_signing(&self) -> CredentialSigningData {
+        let params = bandwidth_credential_params();
+
+        // safety: the creation of the request can only fail if one provided invalid parameters
+        // and we created then specific to this type of the credential so the unwrap is fine
+        let (pedersen_commitments_openings, blind_sign_request) = prepare_blind_sign(
+            params,
+            &[&self.serial_number, &self.binding_number],
+            &self.get_public_attributes(),
+        )
+        .unwrap();
+
+        CredentialSigningData {
+            pedersen_commitments_openings,
+            blind_sign_request,
+            public_attributes_plain: self.get_plain_public_attributes(),
+            typ: self.typ(),
+        }
+    }
+
+    pub fn unblind_signature(
+        &self,
+        validator_vk: &VerificationKey,
+        signing_data: &CredentialSigningData,
+        blinded_signature: BlindedSignature,
+    ) -> Result<Signature, Error> {
+        let public_attributes = self.get_public_attributes();
+        let private_attributes = self.get_private_attributes();
+
+        let params = bandwidth_credential_params();
+        let unblinded_signature = blinded_signature.unblind_and_verify(
+            params,
+            validator_vk,
+            &private_attributes,
+            &public_attributes,
+            &signing_data.blind_sign_request.get_commitment_hash(),
+            &signing_data.pedersen_commitments_openings,
+        )?;
+
+        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,
+        shares: &[SignatureShare],
+    ) -> Result<Signature, Error> {
+        let public_attributes = self.get_public_attributes();
+        let private_attributes = self.get_private_attributes();
+
+        let params = bandwidth_credential_params();
+
+        let mut attributes = Vec::with_capacity(private_attributes.len() + public_attributes.len());
+        attributes.extend_from_slice(&private_attributes);
+        attributes.extend_from_slice(&public_attributes);
+
+        aggregate_signature_shares(params, verification_key, &attributes, shares)
+            .map_err(Error::SignatureAggregationError)
+    }
+
+    // also drops self after the conversion
+    pub fn into_issued_credential(
+        self,
+        aggregate_signature: Signature,
+        epoch_id: EpochId,
+    ) -> IssuedBandwidthCredential {
+        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,
+            self.binding_number,
+            aggregate_signature,
+            (&self.variant_data).into(),
+            self.type_prehashed,
+            epoch_id,
+        )
+    }
+
+    // TODO: is that actually needed?
+    pub fn to_recovery_bytes(&self) -> Vec<u8> {
+        use bincode::Options;
+        // safety: our data format is stable and thus the serialization should not fail
+        make_recovery_bincode_serializer().serialize(self).unwrap()
+    }
+
+    // TODO: is that actually needed?
+    pub fn try_from_recovered_bytes(bytes: &[u8]) -> Result<Self, Error> {
+        use bincode::Options;
+        Ok(make_recovery_bincode_serializer().deserialize(bytes)?)
+    }
+}
+
+fn make_recovery_bincode_serializer() -> impl bincode::Options {
+    use bincode::Options;
+    bincode::DefaultOptions::new()
+        .with_big_endian()
+        .with_varint_encoding()
+}

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

@@ -0,0 +1,193 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::coconut::bandwidth::bandwidth_credential_params;
+use crate::coconut::bandwidth::freepass::FreePassIssuedData;
+use crate::coconut::bandwidth::issuance::{
+    BandwidthCredentialIssuanceDataVariant, IssuanceBandwidthCredential,
+};
+use crate::coconut::bandwidth::voucher::BandwidthVoucherIssuedData;
+use crate::coconut::bandwidth::{CredentialSpendingData, CredentialType};
+use crate::coconut::utils::scalar_serde_helper;
+use crate::error::Error;
+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(Debug, Zeroize, Serialize, Deserialize)]
+pub enum BandwidthCredentialIssuedDataVariant {
+    Voucher(BandwidthVoucherIssuedData),
+    FreePass(FreePassIssuedData),
+}
+
+impl<'a> From<&'a BandwidthCredentialIssuanceDataVariant> for BandwidthCredentialIssuedDataVariant {
+    fn from(value: &'a BandwidthCredentialIssuanceDataVariant) -> Self {
+        match value {
+            BandwidthCredentialIssuanceDataVariant::Voucher(voucher) => {
+                BandwidthCredentialIssuedDataVariant::Voucher(voucher.into())
+            }
+            BandwidthCredentialIssuanceDataVariant::FreePass(freepass) => {
+                BandwidthCredentialIssuedDataVariant::FreePass(freepass.into())
+            }
+        }
+    }
+}
+
+impl From<FreePassIssuedData> for BandwidthCredentialIssuedDataVariant {
+    fn from(value: FreePassIssuedData) -> Self {
+        BandwidthCredentialIssuedDataVariant::FreePass(value)
+    }
+}
+
+impl From<BandwidthVoucherIssuedData> for BandwidthCredentialIssuedDataVariant {
+    fn from(value: BandwidthVoucherIssuedData) -> Self {
+        BandwidthCredentialIssuedDataVariant::Voucher(value)
+    }
+}
+
+impl BandwidthCredentialIssuedDataVariant {
+    pub fn info(&self) -> CredentialType {
+        match self {
+            BandwidthCredentialIssuedDataVariant::Voucher(..) => CredentialType::Voucher,
+            BandwidthCredentialIssuedDataVariant::FreePass(..) => CredentialType::FreePass,
+        }
+    }
+
+    // currently this works under the assumption of there being a single unique public attribute for given variant
+    pub fn public_value_plain(&self) -> String {
+        match self {
+            BandwidthCredentialIssuedDataVariant::Voucher(voucher) => voucher.value_plain(),
+            BandwidthCredentialIssuedDataVariant::FreePass(freepass) => {
+                freepass.expiry_date_plain()
+            }
+        }
+    }
+}
+
+// the only important thing to zeroize here are the private attributes, the rest can be made fully public for what we're concerned
+#[derive(Zeroize, ZeroizeOnDrop, Serialize, Deserialize)]
+pub struct IssuedBandwidthCredential {
+    // private attributes
+    /// a random secret value generated by the client used for double-spending detection
+    #[serde(with = "scalar_serde_helper")]
+    serial_number: PrivateAttribute,
+
+    /// a random secret value generated by the client used to bind multiple credentials together
+    #[serde(with = "scalar_serde_helper")]
+    binding_number: PrivateAttribute,
+
+    /// the underlying aggregated signature on the attributes
+    #[zeroize(skip)]
+    signature: Signature,
+
+    /// data specific to given bandwidth credential, for example a value for bandwidth voucher and expiry date for the free pass
+    variant_data: BandwidthCredentialIssuedDataVariant,
+
+    /// 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 {
+    pub fn new(
+        serial_number: PrivateAttribute,
+        binding_number: PrivateAttribute,
+        signature: Signature,
+        variant_data: BandwidthCredentialIssuedDataVariant,
+        type_prehashed: PublicAttribute,
+        epoch_id: EpochId,
+    ) -> Self {
+        IssuedBandwidthCredential {
+            serial_number,
+            binding_number,
+            signature,
+            variant_data,
+            type_prehashed,
+            epoch_id,
+        }
+    }
+
+    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
+    }
+
+    /// Pack (serialize) this credential data into a stream of bytes using v1 serializer.
+    pub fn pack_v1(&self) -> Vec<u8> {
+        use bincode::Options;
+        // safety: our data format is stable and thus the serialization should not fail
+        make_storable_bincode_serializer().serialize(self).unwrap()
+    }
+
+    /// 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)?)
+    }
+
+    pub fn randomise_signature(&mut self) {
+        let signature_prime = self.signature.randomise(bandwidth_credential_params());
+        self.signature = signature_prime.0
+    }
+
+    pub fn default_parameters() -> Parameters {
+        IssuanceBandwidthCredential::default_parameters()
+    }
+
+    pub fn typ(&self) -> CredentialType {
+        self.variant_data.info()
+    }
+
+    pub fn get_plain_public_attributes(&self) -> Vec<String> {
+        vec![
+            self.variant_data.public_value_plain(),
+            self.typ().to_string(),
+        ]
+    }
+
+    pub fn prepare_for_spending(
+        &self,
+        verification_key: &VerificationKey,
+    ) -> Result<CredentialSpendingData, Error> {
+        let params = bandwidth_credential_params();
+
+        let verify_credential_request = prove_bandwidth_credential(
+            params,
+            verification_key,
+            &self.signature,
+            &self.serial_number,
+            &self.binding_number,
+        )?;
+
+        Ok(CredentialSpendingData {
+            embedded_private_attributes: IssuanceBandwidthCredential::PRIVATE_ATTRIBUTES as usize,
+            verify_credential_request,
+            public_attributes_plain: self.get_plain_public_attributes(),
+            typ: self.typ(),
+            epoch_id: self.epoch_id,
+        })
+    }
+}
+
+fn make_storable_bincode_serializer() -> impl bincode::Options {
+    use bincode::Options;
+    bincode::DefaultOptions::new()
+        .with_big_endian()
+        .with_varint_encoding()
+}

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

@@ -0,0 +1,22 @@
+// Copyright 2021-2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use std::sync::OnceLock;
+
+pub use issuance::IssuanceBandwidthCredential;
+pub use issued::IssuedBandwidthCredential;
+pub use nym_credentials_interface::{
+    CredentialSigningData, CredentialSpendingData, CredentialType, Parameters,
+    UnknownCredentialType,
+};
+
+pub mod freepass;
+pub mod issuance;
+pub mod issued;
+pub mod voucher;
+
+// works under the assumption of having 4 attributes in the underlying credential(s)
+pub fn bandwidth_credential_params() -> &'static Parameters {
+    static BANDWIDTH_CREDENTIAL_PARAMS: OnceLock<Parameters> = OnceLock::new();
+    BANDWIDTH_CREDENTIAL_PARAMS.get_or_init(IssuanceBandwidthCredential::default_parameters)
+}

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

@@ -0,0 +1,137 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::coconut::bandwidth::CredentialSigningData;
+use crate::coconut::utils::scalar_serde_helper;
+use crate::error::Error;
+use nym_api_requests::coconut::BlindSignRequestBody;
+use nym_credentials_interface::{
+    hash_to_scalar, Attribute, BlindSignRequest, BlindedSignature, PublicAttribute,
+};
+use nym_crypto::asymmetric::{encryption, identity};
+use nym_validator_client::nyxd::{Coin, Hash};
+use serde::{Deserialize, Serialize};
+use zeroize::{Zeroize, ZeroizeOnDrop};
+
+#[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
+    #[zeroize(skip)]
+    value: Coin,
+}
+
+impl<'a> From<&'a BandwidthVoucherIssuanceData> for BandwidthVoucherIssuedData {
+    fn from(value: &'a BandwidthVoucherIssuanceData) -> Self {
+        BandwidthVoucherIssuedData {
+            value: value.value.clone(),
+        }
+    }
+}
+
+impl BandwidthVoucherIssuedData {
+    pub fn value(&self) -> &Coin {
+        &self.value
+    }
+
+    pub fn value_plain(&self) -> String {
+        self.value.amount.to_string()
+    }
+}
+
+#[derive(Zeroize, ZeroizeOnDrop, Serialize, Deserialize)]
+pub struct BandwidthVoucherIssuanceData {
+    /// 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
+    #[zeroize(skip)]
+    value: Coin,
+
+    // note: as mentioned above, we're only hashing the value of the coin!
+    #[serde(with = "scalar_serde_helper")]
+    value_prehashed: PublicAttribute,
+
+    /// the hash of the deposit transaction
+    #[zeroize(skip)]
+    deposit_tx_hash: Hash,
+
+    /// base58 encoded private key ensuring the depositer requested these attributes
+    signing_key: identity::PrivateKey,
+
+    /// base58 encoded private key ensuring only this client receives the signature share
+    unused_ed25519: encryption::PrivateKey,
+}
+
+impl BandwidthVoucherIssuanceData {
+    pub fn new(
+        value: impl Into<Coin>,
+        deposit_tx_hash: Hash,
+        signing_key: identity::PrivateKey,
+        unused_ed25519: encryption::PrivateKey,
+    ) -> Self {
+        let value = value.into();
+        let value_prehashed = hash_to_scalar(value.amount.to_string());
+
+        BandwidthVoucherIssuanceData {
+            value,
+            value_prehashed,
+            deposit_tx_hash,
+            signing_key,
+            unused_ed25519,
+        }
+    }
+
+    pub fn request_plaintext(request: &BlindSignRequest, tx_hash: Hash) -> Vec<u8> {
+        let mut message = request.to_bytes();
+        message.extend_from_slice(tx_hash.as_bytes());
+        message
+    }
+
+    fn request_signature(&self, signing_request: &CredentialSigningData) -> identity::Signature {
+        let message =
+            Self::request_plaintext(&signing_request.blind_sign_request, self.deposit_tx_hash);
+        self.signing_key.sign(message)
+    }
+
+    pub fn create_blind_sign_request_body(
+        &self,
+        signing_request: &CredentialSigningData,
+    ) -> BlindSignRequestBody {
+        let request_signature = self.request_signature(signing_request);
+
+        BlindSignRequestBody::new(
+            signing_request.blind_sign_request.clone(),
+            self.deposit_tx_hash,
+            request_signature,
+            signing_request.public_attributes_plain.clone(),
+        )
+    }
+
+    pub async fn obtain_blinded_credential(
+        &self,
+        client: &nym_validator_client::client::NymApiClient,
+        request_body: &BlindSignRequestBody,
+    ) -> Result<BlindedSignature, Error> {
+        let server_response = client.blind_sign(request_body).await?;
+        Ok(server_response.blinded_signature)
+    }
+
+    pub fn value_plain(&self) -> String {
+        self.value.amount.to_string()
+    }
+
+    pub fn value_attribute(&self) -> &Attribute {
+        &self.value_prehashed
+    }
+
+    pub fn tx_hash(&self) -> Hash {
+        self.deposit_tx_hash
+    }
+
+    pub fn identity_key(&self) -> &identity::PrivateKey {
+        &self.signing_key
+    }
+
+    pub fn encryption_key(&self) -> &encryption::PrivateKey {
+        &self.unused_ed25519
+    }
+}

common/credentials/src/coconut/mod.rs

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

common/credentials/src/coconut/utils.rs

@@ -1,17 +1,15 @@
-// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// Copyright 2021-2024 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::coconut::bandwidth::BandwidthVoucher;
+use crate::coconut::bandwidth::IssuanceBandwidthCredential;
 use crate::error::Error;
 use log::{debug, warn};
-use nym_api_requests::coconut::BlindSignRequestBody;
-use nym_coconut_interface::{
-    aggregate_signature_shares, aggregate_verification_keys, prove_bandwidth_credential, Attribute,
-    Credential, Parameters, Signature, SignatureShare, VerificationKey,
+use nym_credentials_interface::{
+    aggregate_verification_keys, Signature, SignatureShare, VerificationKey,
 };
 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() {
@@ -30,44 +28,8 @@ pub async fn obtain_aggregate_verification_key(
     Ok(aggregate_verification_keys(&shares, Some(&indices))?)
 }
 
-async fn obtain_partial_credential(
-    params: &Parameters,
-    voucher: &BandwidthVoucher,
-    client: &nym_validator_client::client::NymApiClient,
-    validator_vk: &VerificationKey,
-) -> Result<Signature, Error> {
-    let public_attributes_plain = voucher.get_public_attributes_plain();
-    let blind_sign_request = voucher.blind_sign_request();
-    let request_signature = voucher.sign();
-
-    let blind_sign_request_body = BlindSignRequestBody::new(
-        blind_sign_request.clone(),
-        voucher.tx_hash(),
-        request_signature,
-        public_attributes_plain,
-    );
-    let response = client.blind_sign(&blind_sign_request_body).await?;
-
-    let blinded_signature = response.blinded_signature;
-
-    let public_attributes = voucher.get_public_attributes();
-    let private_attributes = voucher.get_private_attributes();
-
-    let unblinded_signature = blinded_signature.unblind_and_verify(
-        params,
-        validator_vk,
-        &private_attributes,
-        &public_attributes,
-        &blind_sign_request.get_commitment_hash(),
-        voucher.pedersen_commitments_openings(),
-    )?;
-
-    Ok(unblinded_signature)
-}
-
 pub async fn obtain_aggregate_signature(
-    params: &Parameters,
-    voucher: &BandwidthVoucher,
+    voucher: &IssuanceBandwidthCredential,
     coconut_api_clients: &[CoconutApiClient],
     threshold: u64,
 ) -> Result<Signature, Error> {
@@ -75,16 +37,9 @@ pub async fn obtain_aggregate_signature(
         return Err(Error::NoValidatorsAvailable);
     }
     let mut shares = Vec::with_capacity(coconut_api_clients.len());
-    let validators_partial_vks: Vec<_> = coconut_api_clients
-        .iter()
-        .map(|api_client| api_client.verification_key.clone())
-        .collect();
-    let indices: Vec<_> = coconut_api_clients
-        .iter()
-        .map(|api_client| api_client.node_id)
-        .collect();
-    let verification_key =
-        aggregate_verification_keys(&validators_partial_vks, Some(indices.as_ref()))?;
+    let verification_key = obtain_aggregate_verification_key(coconut_api_clients)?;
+
+    let request = voucher.prepare_for_signing();
 
     for coconut_api_client in coconut_api_clients.iter() {
         debug!(
@@ -92,13 +47,13 @@ pub async fn obtain_aggregate_signature(
             coconut_api_client.api_client.api_url()
         );
 
-        match obtain_partial_credential(
-            params,
-            voucher,
-            &coconut_api_client.api_client,
-            &coconut_api_client.verification_key,
-        )
-        .await
+        match voucher
+            .obtain_partial_bandwidth_voucher_credential(
+                &coconut_api_client.api_client,
+                &coconut_api_client.verification_key,
+                Some(request.clone()),
+            )
+            .await
         {
             Ok(signature) => {
                 let share = SignatureShare::new(signature, coconut_api_client.node_id);
@@ -116,42 +71,27 @@ pub async fn obtain_aggregate_signature(
         return Err(Error::NotEnoughShares);
     }
 
-    let public_attributes = voucher.get_public_attributes();
-    let private_attributes = voucher.get_private_attributes();
-
-    let mut attributes = Vec::with_capacity(private_attributes.len() + public_attributes.len());
-    attributes.extend_from_slice(&private_attributes);
-    attributes.extend_from_slice(&public_attributes);
-
-    aggregate_signature_shares(params, &verification_key, &attributes, &shares)
-        .map_err(Error::SignatureAggregationError)
+    voucher.aggregate_signature_shares(&verification_key, &shares)
 }
 
-// TODO: better type flow
-#[allow(clippy::too_many_arguments)]
-pub fn prepare_credential_for_spending(
-    params: &Parameters,
-    voucher_value: u64,
-    voucher_info: String,
-    serial_number: &Attribute,
-    binding_number: &Attribute,
-    epoch_id: u64,
-    signature: &Signature,
-    verification_key: &VerificationKey,
-) -> Result<Credential, Error> {
-    let theta = prove_bandwidth_credential(
-        params,
-        verification_key,
-        signature,
-        serial_number,
-        binding_number,
-    )?;
+pub(crate) mod scalar_serde_helper {
+    use bls12_381::Scalar;
+    use serde::{Deserialize, Deserializer, Serialize, Serializer};
+    use zeroize::Zeroizing;
 
-    Ok(Credential::new(
-        BandwidthVoucher::ENCODED_ATTRIBUTES,
-        theta,
-        voucher_value,
-        voucher_info,
-        epoch_id,
-    ))
+    pub fn serialize<S: Serializer>(scalar: &Scalar, serializer: S) -> Result<S::Ok, S::Error> {
+        scalar.to_bytes().serialize(serializer)
+    }
+
+    pub fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Scalar, D::Error> {
+        let b = <[u8; 32]>::deserialize(deserializer)?;
+
+        // make sure the bytes get zeroed
+        let bytes = Zeroizing::new(b);
+
+        let maybe_scalar: Option<Scalar> = Scalar::from_bytes(&bytes).into();
+        maybe_scalar.ok_or(serde::de::Error::custom(
+            "did not construct a valid bls12-381 scalar out of the provided bytes",
+        ))
+    }
 }

common/credentials/src/error.rs

@@ -1,7 +1,7 @@
 // Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
-use nym_coconut_interface::CoconutError;
+use nym_credentials_interface::CoconutError;
 use nym_crypto::asymmetric::encryption::KeyRecoveryError;
 use nym_validator_client::ValidatorClientError;
 
@@ -12,6 +12,9 @@ pub enum Error {
     #[error("IO error")]
     IOError(#[from] std::io::Error),
 
+    #[error("failed to (de)serialize credential structure: {0}")]
+    SerializationFailure(#[from] bincode::Error),
+
     #[error("The detailed description is yet to be determined")]
     BandwidthCredentialError,
 
@@ -41,4 +44,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

@@ -4,4 +4,8 @@
 pub mod coconut;
 pub mod error;
 
+pub use coconut::bandwidth::{
+    CredentialSigningData, CredentialSpendingData, IssuanceBandwidthCredential,
+    IssuedBandwidthCredential,
+};
 pub use coconut::utils::{obtain_aggregate_signature, obtain_aggregate_verification_key};

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/network-defaults/src/lib.rs

@@ -33,6 +33,7 @@ pub struct NymContracts {
     pub ephemera_contract_address: Option<String>,
     pub service_provider_directory_contract_address: Option<String>,
     pub name_service_contract_address: Option<String>,
+    pub swapper_contract_address: Option<String>,
 }
 
 // I wanted to use the simpler `NetworkDetails` name, but there's a clash
@@ -140,6 +141,7 @@ impl NymNetworkDetails {
             ))
             .with_name_service_contract(get_optional_env(var_names::NAME_SERVICE_CONTRACT_ADDRESS))
             .with_explorer_api(get_optional_env(var_names::EXPLORER_API))
+            .with_swapper_contract(get_optional_env(var_names::SWAPPER_CONTRACT_ADDRESS))
     }
 
     pub fn new_mainnet() -> Self {
@@ -170,6 +172,7 @@ impl NymNetworkDetails {
                 ephemera_contract_address: parse_optional_str(mainnet::EPHEMERA_CONTRACT_ADDRESS),
                 service_provider_directory_contract_address: None,
                 name_service_contract_address: None,
+                swapper_contract_address: None,
             },
             explorer_api: parse_optional_str(mainnet::EXPLORER_API),
         }
@@ -289,6 +292,12 @@ impl NymNetworkDetails {
         self.explorer_api = endpoint.map(Into::into);
         self
     }
+
+    #[must_use]
+    pub fn with_swapper_contract<S: Into<String>>(mut self, endpoint: Option<S>) -> Self {
+        self.contracts.swapper_contract_address = endpoint.map(Into::into);
+        self
+    }
 }
 
 #[derive(Debug, Copy, Serialize, Deserialize, Clone, PartialEq, Eq)]
@@ -457,6 +466,9 @@ pub const ETH_ERC20_APPROVE_FUNCTION_NAME: &str = "approve";
 /// How much bandwidth (in bytes) one token can buy
 pub const BYTES_PER_UTOKEN: u64 = 1024;
 
+/// How much bandwidth (in bytes) one freepass provides
+pub const BYTES_PER_FREEPASS: u64 = 1024 * 1024 * 1024; // 1GB
+
 /// Threshold for claiming more bandwidth: 1 MB
 pub const REMAINING_BANDWIDTH_THRESHOLD: i64 = 1024 * 1024;
 /// How many ERC20 tokens should be burned to buy bandwidth
@@ -466,10 +478,6 @@ pub const UTOKENS_TO_BURN: u64 = TOKENS_TO_BURN * 1000000;
 /// Default bandwidth (in bytes) that we try to buy
 pub const BANDWIDTH_VALUE: u64 = UTOKENS_TO_BURN * BYTES_PER_UTOKEN;
 
-pub const VOUCHER_INFO: &str = "BandwidthVoucher";
-
-pub const ETH_MIN_BLOCK_DEPTH: usize = 7;
-
 /// Defaults Cosmos Hub/ATOM path
 pub const COSMOS_DERIVATION_PATH: &str = "m/44'/118'/0'/0/0";
 // as set by validators in their configs

common/network-defaults/src/mainnet.rs

@@ -21,6 +21,7 @@ pub const GROUP_CONTRACT_ADDRESS: &str = "n19lc9u84cz0yz3fww5283nucc9yvr8gsjmgeu
 pub const MULTISIG_CONTRACT_ADDRESS: &str = "n19lc9u84cz0yz3fww5283nucc9yvr8gsjmgeul0";
 pub const COCONUT_DKG_CONTRACT_ADDRESS: &str = "n19lc9u84cz0yz3fww5283nucc9yvr8gsjmgeul0";
 pub const EPHEMERA_CONTRACT_ADDRESS: &str = "n19lc9u84cz0yz3fww5283nucc9yvr8gsjmgeul0";
+pub const SWAPPER_CONTRACT_ADDRESS: &str = "n19lc9u84cz0yz3fww5283nucc9yvr8gsjmgeul0";
 pub const REWARDING_VALIDATOR_ADDRESS: &str = "n10yyd98e2tuwu0f7ypz9dy3hhjw7v772q6287gy";
 
 pub const STATISTICS_SERVICE_DOMAIN_ADDRESS: &str = "https://mainnet-stats.nymte.ch:8090/";
@@ -106,6 +107,10 @@ pub fn export_to_env() {
         var_names::EPHEMERA_CONTRACT_ADDRESS,
         EPHEMERA_CONTRACT_ADDRESS,
     );
+    set_var_to_default(
+        var_names::SWAPPER_CONTRACT_ADDRESS,
+        SWAPPER_CONTRACT_ADDRESS,
+    );
     set_var_to_default(
         var_names::REWARDING_VALIDATOR_ADDRESS,
         REWARDING_VALIDATOR_ADDRESS,
@@ -151,6 +156,10 @@ pub fn export_to_env_if_not_set() {
         var_names::COCONUT_DKG_CONTRACT_ADDRESS,
         COCONUT_DKG_CONTRACT_ADDRESS,
     );
+    set_var_conditionally_to_default(
+        var_names::SWAPPER_CONTRACT_ADDRESS,
+        SWAPPER_CONTRACT_ADDRESS,
+    );
     set_var_conditionally_to_default(
         var_names::EPHEMERA_CONTRACT_ADDRESS,
         EPHEMERA_CONTRACT_ADDRESS,

common/network-defaults/src/var_names.rs

@@ -19,6 +19,7 @@ pub const GROUP_CONTRACT_ADDRESS: &str = "GROUP_CONTRACT_ADDRESS";
 pub const MULTISIG_CONTRACT_ADDRESS: &str = "MULTISIG_CONTRACT_ADDRESS";
 pub const COCONUT_DKG_CONTRACT_ADDRESS: &str = "COCONUT_DKG_CONTRACT_ADDRESS";
 pub const EPHEMERA_CONTRACT_ADDRESS: &str = "EPHEMERA_CONTRACT_ADDRESS";
+pub const SWAPPER_CONTRACT_ADDRESS: &str = "SWAPPER_CONTRACT_ADDRESS";
 pub const REWARDING_VALIDATOR_ADDRESS: &str = "REWARDING_VALIDATOR_ADDRESS";
 pub const STATISTICS_SERVICE_DOMAIN_ADDRESS: &str = "STATISTICS_SERVICE_DOMAIN_ADDRESS";
 pub const SERVICE_PROVIDER_DIRECTORY_CONTRACT_ADDRESS: &str =

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/impls/clone.rs

@@ -1,4 +1,4 @@
-use crate::{BlindSignRequest, BlindedSignature, Bytable, Theta};
+use crate::{BlindSignRequest, BlindedSignature, Bytable, VerifyCredentialRequest};
 
 macro_rules! impl_clone {
     ($struct:ident) => {
@@ -12,4 +12,4 @@ macro_rules! impl_clone {
 
 impl_clone!(BlindSignRequest);
 impl_clone!(BlindedSignature);
-impl_clone!(Theta);
+impl_clone!(VerifyCredentialRequest);

common/nymcoconut/src/impls/serde.rs

@@ -1,7 +1,8 @@
 use crate::elgamal::PrivateKey;
 use crate::scheme::SecretKey;
 use crate::{
-    Base58, BlindSignRequest, BlindedSignature, PublicKey, Signature, Theta, VerificationKey,
+    Base58, BlindSignRequest, BlindedSignature, PublicKey, Signature, VerificationKey,
+    VerifyCredentialRequest,
 };
 use serde::de::Unexpected;
 use serde::{de::Error, de::Visitor, Deserialize, Deserializer, Serialize, Serializer};
@@ -53,4 +54,4 @@ impl_serde!(PrivateKey, V4);
 impl_serde!(BlindSignRequest, V5);
 impl_serde!(BlindedSignature, V6);
 impl_serde!(Signature, V7);
-impl_serde!(Theta, V8);
+impl_serde!(VerifyCredentialRequest, V8);

common/nymcoconut/src/lib.rs

@@ -14,6 +14,7 @@ pub use scheme::issuance::blind_sign;
 pub use scheme::issuance::prepare_blind_sign;
 pub use scheme::issuance::verify_partial_blind_signature;
 pub use scheme::issuance::BlindSignRequest;
+pub use scheme::keygen::keygen;
 pub use scheme::keygen::ttp_keygen;
 pub use scheme::keygen::KeyPair;
 pub use scheme::keygen::SecretKey;
@@ -23,7 +24,8 @@ 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::Theta;
+pub use scheme::verification::BlindedSerialNumber;
+pub use scheme::verification::VerifyCredentialRequest;
 pub use scheme::BlindedSignature;
 pub use scheme::Signature;
 pub use scheme::SignatureShare;

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/keygen.rs

@@ -565,7 +565,6 @@ impl TryFrom<&[u8]> for KeyPair {
 /// Generate a single Coconut keypair ((x, y0, y1...), (g2^x, g2^y0, ...)).
 /// It is not suitable for threshold credentials as all subsequent calls to `keygen` generate keys
 /// that are independent of each other.
-#[cfg(test)]
 pub fn keygen(params: &Parameters) -> KeyPair {
     let attributes = params.gen_hs().len();
 

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/setup.rs

@@ -44,11 +44,11 @@ impl Parameters {
         })
     }
 
-    pub(crate) fn gen1(&self) -> &G1Affine {
+    pub fn gen1(&self) -> &G1Affine {
         &self.g1
     }
 
-    pub(crate) fn gen2(&self) -> &G2Affine {
+    pub fn gen2(&self) -> &G2Affine {
         &self.g2
     }
 
@@ -56,7 +56,7 @@ impl Parameters {
         &self._g2_prepared_miller
     }
 
-    pub(crate) fn gen_hs(&self) -> &[G1Affine] {
+    pub fn gen_hs(&self) -> &[G1Affine] {
         &self.hs
     }
 

common/nymcoconut/src/scheme/verification.rs

@@ -1,41 +1,40 @@
-// 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
 #[derive(Debug, PartialEq, Eq)]
-pub struct Theta {
+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
     pub pi_v: ProofKappaZeta,
 }
 
-impl TryFrom<&[u8]> for Theta {
+impl TryFrom<&[u8]> for VerifyCredentialRequest {
     type Error = CoconutError;
 
-    fn try_from(bytes: &[u8]) -> Result<Theta> {
+    fn try_from(bytes: &[u8]) -> Result<VerifyCredentialRequest> {
         if bytes.len() < 288 {
             return Err(
                 CoconutError::Deserialization(
@@ -53,20 +52,15 @@ impl TryFrom<&[u8]> for Theta {
             ),
         )?;
 
-        // 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..])?;
 
-        Ok(Theta {
+        Ok(VerifyCredentialRequest {
             blinded_message,
             blinded_serial_number,
             credential,
@@ -75,7 +69,7 @@ impl TryFrom<&[u8]> for Theta {
     }
 }
 
-impl Theta {
+impl VerifyCredentialRequest {
     fn verify_proof(&self, params: &Parameters, verification_key: &VerificationKey) -> bool {
         self.pi_v.verify(
             params,
@@ -87,7 +81,7 @@ impl Theta {
 
     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)
     }
 
@@ -107,29 +101,30 @@ impl Theta {
         bytes
     }
 
-    pub fn from_bytes(bytes: &[u8]) -> Result<Theta> {
-        Theta::try_from(bytes)
+    pub fn from_bytes(bytes: &[u8]) -> Result<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()
     }
 }
 
-impl Bytable for Theta {
+impl Bytable for VerifyCredentialRequest {
     fn to_byte_vec(&self) -> Vec<u8> {
         self.to_bytes()
     }
 
     fn try_from_byte_slice(slice: &[u8]) -> Result<Self> {
-        Theta::try_from(slice)
+        VerifyCredentialRequest::try_from(slice)
     }
 }
 
-impl Base58 for Theta {}
+impl Base58 for VerifyCredentialRequest {}
 
 pub fn compute_kappa(
     params: &Parameters,
@@ -156,7 +151,7 @@ pub fn prove_bandwidth_credential(
     signature: &Signature,
     serial_number: &Attribute,
     binding_number: &Attribute,
-) -> Result<Theta> {
+) -> Result<VerifyCredentialRequest> {
     if verification_key.beta_g2.len() < 2 {
         return Err(
             CoconutError::Verification(
@@ -196,9 +191,9 @@ pub fn prove_bandwidth_credential(
         &blinded_serial_number,
     );
 
-    Ok(Theta {
+    Ok(VerifyCredentialRequest {
         blinded_message,
-        blinded_serial_number,
+        blinded_serial_number: blinded_serial_number.into(),
         credential: signature_prime,
         pi_v,
     })
@@ -256,7 +251,7 @@ pub fn check_vk_pairing(
 pub fn verify_credential(
     params: &Parameters,
     verification_key: &VerificationKey,
-    theta: &Theta,
+    theta: &VerifyCredentialRequest,
     public_attributes: &[&Attribute],
 ) -> bool {
     if public_attributes.len() + theta.pi_v.private_attributes_len()
@@ -358,6 +353,9 @@ mod tests {
         .unwrap();
 
         let bytes = theta.to_bytes();
-        assert_eq!(Theta::try_from(bytes.as_slice()).unwrap(), theta);
+        assert_eq!(
+            VerifyCredentialRequest::try_from(bytes.as_slice()).unwrap(),
+            theta
+        );
     }
 }

common/nymcoconut/src/tests/helpers.rs

@@ -12,7 +12,7 @@ pub fn theta_from_keys_and_attributes(
     coconut_keypairs: &Vec<KeyPair>,
     indices: &[scheme::SignerIndex],
     public_attributes: &[&PublicAttribute],
-) -> Result<Theta, CoconutError> {
+) -> Result<VerifyCredentialRequest, CoconutError> {
     let serial_number = params.random_scalar();
     let binding_number = params.random_scalar();
     let private_attributes = vec![&serial_number, &binding_number];

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/nyxd-scraper/Cargo.toml

@@ -21,6 +21,7 @@ sqlx = { workspace = true, features = ["runtime-tokio-rustls", "sqlite", "macros
 tendermint.workspace = true
 tendermint-rpc = { workspace = true, features = ["websocket-client", "http-client"] }
 thiserror.workspace = true
+time = { workspace = true }
 tokio = { workspace = true, features = ["full"] }
 tokio-stream = "0.1.14"
 tokio-util = { version = "0.7.10", features = ["rt"]}

common/nyxd-scraper/src/error.rs

@@ -84,7 +84,7 @@ pub enum ScraperError {
     EmptyBlockData { query: String },
 
     #[error("reached maximum number of allowed errors for subscription events")]
-    MaximumSubscriptionFailures,
+    MaximumWebSocketFailures,
 
     #[error("failed to begin storage tx: {source}")]
     StorageTxBeginFailure {

common/nyxd-scraper/src/scraper/mod.rs

@@ -6,11 +6,10 @@ use crate::block_requester::BlockRequester;
 use crate::error::ScraperError;
 use crate::modules::{BlockModule, MsgModule, TxModule};
 use crate::rpc_client::RpcClient;
-use crate::scraper::subscriber::{run_websocket_driver, ChainSubscriber};
+use crate::scraper::subscriber::ChainSubscriber;
 use crate::storage::ScraperStorage;
 use std::path::PathBuf;
 use std::sync::Arc;
-use tendermint_rpc::WebSocketClientDriver;
 use tokio::sync::mpsc::{channel, unbounded_channel};
 use tokio::sync::Notify;
 use tokio_util::sync::CancellationToken;
@@ -67,20 +66,15 @@ impl NyxdScraperBuilder {
         block_processor.set_tx_modules(self.tx_modules);
         block_processor.set_msg_modules(self.msg_modules);
 
-        let mut chain_subscriber = ChainSubscriber::new(
+        let chain_subscriber = ChainSubscriber::new(
             &scraper.config.websocket_url,
             scraper.cancel_token.clone(),
+            scraper.task_tracker.clone(),
             processing_tx,
         )
         .await?;
-        let ws_driver = chain_subscriber.ws_driver();
 
-        scraper.start_tasks(
-            block_requester,
-            block_processor,
-            chain_subscriber,
-            ws_driver,
-        );
+        scraper.start_tasks(block_requester, block_processor, chain_subscriber);
 
         Ok(scraper)
     }
@@ -141,7 +135,6 @@ impl NyxdScraper {
         mut block_requester: BlockRequester,
         mut block_processor: BlockProcessor,
         mut chain_subscriber: ChainSubscriber,
-        ws_driver: WebSocketClientDriver,
     ) {
         self.task_tracker
             .spawn(async move { block_requester.run().await });
@@ -149,8 +142,7 @@ impl NyxdScraper {
             .spawn(async move { block_processor.run().await });
         self.task_tracker
             .spawn(async move { chain_subscriber.run().await });
-        self.task_tracker
-            .spawn(run_websocket_driver(ws_driver, self.cancel_token.clone()));
+
         self.task_tracker.close();
     }
 
@@ -176,21 +168,16 @@ impl NyxdScraper {
             rpc_client,
         )
         .await?;
-        let mut chain_subscriber = ChainSubscriber::new(
+        let chain_subscriber = ChainSubscriber::new(
             &self.config.websocket_url,
             self.cancel_token.clone(),
+            self.task_tracker.clone(),
             processing_tx,
         )
         .await?;
-        let ws_driver = chain_subscriber.ws_driver();
 
         // spawn them
-        self.start_tasks(
-            block_requester,
-            block_processor,
-            chain_subscriber,
-            ws_driver,
-        );
+        self.start_tasks(block_requester, block_processor, chain_subscriber);
 
         Ok(())
     }
@@ -201,10 +188,18 @@ impl NyxdScraper {
     }
 
     pub async fn stop(self) {
-        info!("stopping the chain scrapper");
+        info!("stopping the chain scraper");
         assert!(self.task_tracker.is_closed());
 
         self.cancel_token.cancel();
         self.task_tracker.wait().await
     }
+
+    pub fn cancel_token(&self) -> CancellationToken {
+        self.cancel_token.clone()
+    }
+
+    pub fn is_cancelled(&self) -> bool {
+        self.cancel_token.is_cancelled()
+    }
 }

common/nyxd-scraper/src/scraper/subscriber.rs

@@ -6,18 +6,25 @@ use crate::error::ScraperError;
 use tendermint_rpc::event::Event;
 use tendermint_rpc::query::EventType;
 use tendermint_rpc::{SubscriptionClient, WebSocketClient, WebSocketClientDriver};
+use time::{Duration, OffsetDateTime};
 use tokio::sync::mpsc::UnboundedSender;
 use tokio_stream::StreamExt;
 use tokio_util::sync::CancellationToken;
+use tokio_util::task::TaskTracker;
 use tracing::{error, info, warn};
 use url::Url;
 
 const MAX_FAILURES: usize = 10;
+const MAX_RECONNECTION_ATTEMPTS: usize = 8;
+const SOCKET_FAILURE_RESET: Duration = Duration::hours(2);
 
 pub struct ChainSubscriber {
     cancel: CancellationToken,
+    task_tracker: TaskTracker,
+
     block_sender: UnboundedSender<BlockToProcess>,
 
+    websocket_endpoint: Url,
     websocket_client: WebSocketClient,
     websocket_driver: Option<WebSocketClientDriver>,
 }
@@ -26,6 +33,7 @@ impl ChainSubscriber {
     pub async fn new(
         websocket_endpoint: &Url,
         cancel: CancellationToken,
+        task_tracker: TaskTracker,
         block_sender: UnboundedSender<BlockToProcess>,
     ) -> Result<Self, ScraperError> {
         // sure, we could have just used websocket client entirely, but let's keep the logic for
@@ -39,7 +47,9 @@ impl ChainSubscriber {
 
         Ok(ChainSubscriber {
             cancel,
+            task_tracker,
             block_sender,
+            websocket_endpoint: websocket_endpoint.clone(),
             websocket_client: client,
             websocket_driver: Some(driver),
         })
@@ -53,8 +63,48 @@ impl ChainSubscriber {
         Ok(())
     }
 
-    pub(crate) async fn run(&mut self) -> Result<(), ScraperError> {
-        let _drop_guard = self.cancel.clone().drop_guard();
+    async fn remake_connection(&mut self) -> Result<(), ScraperError> {
+        info!(
+            "attempting to reestablish connection to {}",
+            self.websocket_endpoint
+        );
+
+        let (client, driver) = WebSocketClient::new(self.websocket_endpoint.as_str())
+            .await
+            .map_err(|source| ScraperError::WebSocketConnectionFailure {
+                url: self.websocket_endpoint.to_string(),
+                source,
+            })?;
+        self.websocket_client = client;
+        self.websocket_driver = Some(driver);
+
+        info!(
+            "managed to reestablish the websocket connection to {}",
+            self.websocket_endpoint
+        );
+        Ok(())
+    }
+
+    /// Returns whether the method exited due to the cancellation
+    async fn run_chain_subscription(&mut self) -> Result<bool, ScraperError> {
+        let Some(ws_driver) = self.websocket_driver.take() else {
+            error!("the websocket driver hasn't been created - we probably failed to establish the connection");
+            return Ok(false);
+        };
+
+        let driver_cancel = CancellationToken::new();
+        let _driver_guard = driver_cancel.clone().drop_guard();
+
+        // spawn the websocket driver task
+        let driver_handle = {
+            self.task_tracker.reopen();
+            let handle = self
+                .task_tracker
+                .spawn(run_websocket_driver(ws_driver, driver_cancel));
+            self.task_tracker.close();
+            handle
+        };
+        tokio::pin!(driver_handle);
 
         info!("creating chain subscription");
         let mut subs = self
@@ -70,12 +120,17 @@ impl ChainSubscriber {
             tokio::select! {
                 _ = self.cancel.cancelled() => {
                     info!("received cancellation token");
-                    break
+                    // note: `_driver_guard` will get dropped here thus causing cancellation of the driver task
+                    return Ok(true)
+                }
+                _ = &mut driver_handle => {
+                    error!("our websocket driver has finished execution");
+                    return Ok(self.cancel.is_cancelled())
                 }
                 maybe_event = subs.next() => {
                     let Some(maybe_event) = maybe_event else {
                         warn!("stopped receiving new events");
-                        break;
+                        return Ok(false)
                     };
                     match maybe_event {
                         Ok(event) => {
@@ -92,38 +147,95 @@ impl ChainSubscriber {
                         }
                     }
                     if failures >= MAX_FAILURES {
-                        // note: the drop_guard will get dropped and thus cause a shutdown
-                        return Err(ScraperError::MaximumSubscriptionFailures);
+                        return Ok(false)
                     }
                 }
             }
         }
-        Ok(())
     }
 
-    pub(crate) fn ws_driver(&mut self) -> WebSocketClientDriver {
-        #[allow(clippy::expect_used)]
-        self.websocket_driver
-            .take()
-            .expect("websocket driver has already been started!")
+    async fn websocket_backoff(&mut self, failure_count: usize) -> bool {
+        const MINIMUM_WAIT_MS: u64 = 10_000;
+        const INCREMENTAL_WAIT_MS: u64 = 30_000;
+
+        let backoff_duration_ms = MINIMUM_WAIT_MS + INCREMENTAL_WAIT_MS * failure_count as u64;
+        info!("going to wait {backoff_duration_ms} ms before re-attempting the reconnection");
+
+        tokio::select! {
+            _ = self.cancel.cancelled() => {
+                info!("received cancellation token");
+                true
+            }
+            _ = tokio::time::sleep(std::time::Duration::from_millis(backoff_duration_ms)) => false,
+        }
+    }
+
+    pub(crate) async fn run(&mut self) -> Result<(), ScraperError> {
+        let _drop_guard = self.cancel.clone().drop_guard();
+        let mut socket_failures = 0;
+        let mut last_failure = OffsetDateTime::now_utc();
+
+        loop {
+            if self.cancel.is_cancelled() {
+                return Ok(());
+            }
+
+            match self.run_chain_subscription().await {
+                Ok(cancelled) => {
+                    if cancelled {
+                        // we're in the middle of a shutdown
+                        return Ok(());
+                    }
+                    socket_failures += 1;
+                }
+                Err(err) => {
+                    error!("failed to create chain subscription: {err}");
+                    socket_failures += 1;
+                }
+            }
+
+            warn!("current socket failure count: {socket_failures}. the last failure was at {last_failure}");
+
+            let now = OffsetDateTime::now_utc();
+
+            // if it's been a while since the last failure, reset the count
+            if now - last_failure > SOCKET_FAILURE_RESET {
+                warn!("resetting the failure count to 1");
+                socket_failures = 1;
+            }
+            last_failure = now;
+
+            if socket_failures >= MAX_RECONNECTION_ATTEMPTS {
+                error!("reached the maximum allowed failure count");
+                return Err(ScraperError::MaximumWebSocketFailures);
+            }
+
+            // BACKOFF
+            let cancelled = self.websocket_backoff(socket_failures).await;
+            if cancelled {
+                return Ok(());
+            }
+
+            if let Err(err) = self.remake_connection().await {
+                error!("failed to re-establish the websocket connection: {err}");
+            }
+        }
     }
 }
 
-pub async fn run_websocket_driver(driver: WebSocketClientDriver, cancel: CancellationToken) {
+pub async fn run_websocket_driver(driver: WebSocketClientDriver, driver_cancel: CancellationToken) {
     info!("starting websocket driver");
     tokio::select! {
-        _ = cancel.cancelled() => {
+        _ = driver_cancel.cancelled() => {
             info!("received cancellation token")
         }
         res = driver.run() => {
             match res {
                 Ok(_) => info!("our websocket driver has finished execution"),
                 Err(err) => {
-                    // TODO: in the future just attempt to reconnect
-                    error!("our websocket driver has errored out: {err}")
+                    error!("our websocket driver has errored out: {err}");
                 }
             }
-            cancel.cancel()
         }
     }
 }

common/topology/Cargo.toml

@@ -12,7 +12,7 @@ documentation = { workspace = true }
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-bs58 = "0.4"
+bs58 = { workspace = true }
 log = { workspace = true }
 rand = { version = "0.7.3", features = ["wasm-bindgen"] }
 thiserror = { workspace = true }

common/types/Cargo.toml

@@ -31,7 +31,6 @@ nym-validator-client = { path = "../../common/client-libs/validator-client" }
 nym-mixnet-contract-common = { path = "../../common/cosmwasm-smart-contracts/mixnet-contract" }
 nym-vesting-contract-common = { path = "../../common/cosmwasm-smart-contracts/vesting-contract" }
 nym-config = { path = "../../common/config" }
-nym-coconut-interface = { path = "../../common/coconut-interface" }
 nym-crypto = { path = "../../common/crypto", features = ["asymmetric"] }
 
 [dev-dependencies]

contracts/Cargo.lock

@@ -116,6 +116,15 @@ version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "771fe0050b883fcc3ea2359b1a96bcfbc090b7116eae7c3c512c7a083fdf23d3"
 
+[[package]]
+name = "bs58"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f5353f36341f7451062466f0b755b96ac3a9547e4d7f6b70d603fc721a7d7896"
+dependencies = [
+ "tinyvec",
+]
+
 [[package]]
 name = "bumpalo"
 version = "3.12.1"
@@ -178,6 +187,7 @@ dependencies = [
 name = "coconut-test"
 version = "0.1.0"
 dependencies = [
+ "bs58 0.4.0",
  "cosmwasm-std",
  "cosmwasm-storage",
  "cw-controllers",
@@ -194,8 +204,10 @@ dependencies = [
  "nym-coconut-dkg-common",
  "nym-group-contract-common",
  "nym-multisig-contract-common",
+ "rand_chacha 0.2.2",
  "schemars",
  "serde",
+ "subtle-encoding",
  "thiserror",
 ]
 
@@ -819,7 +831,7 @@ checksum = "89ca545a94061b6365f2c7355b4b32bd20df3ff95f02da9329b34ccc3bd6ee72"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.32",
+ "syn 2.0.49",
 ]
 
 [[package]]
@@ -1225,7 +1237,6 @@ dependencies = [
  "cw4-group",
  "nym-coconut-dkg-common",
  "nym-group-contract-common",
- "rusty-fork",
  "semver",
  "serde",
  "thiserror",
@@ -1248,7 +1259,7 @@ dependencies = [
 name = "nym-contracts-common"
 version = "0.5.0"
 dependencies = [
- "bs58",
+ "bs58 0.5.0",
  "cosmwasm-schema",
  "cosmwasm-std",
  "schemars",
@@ -1260,7 +1271,7 @@ dependencies = [
 name = "nym-crypto"
 version = "0.4.0"
 dependencies = [
- "bs58",
+ "bs58 0.5.0",
  "ed25519-dalek",
  "nym-pemstore",
  "nym-sphinx-types",
@@ -1316,7 +1327,7 @@ dependencies = [
 name = "nym-mixnet-contract"
 version = "1.5.1"
 dependencies = [
- "bs58",
+ "bs58 0.4.0",
  "cosmwasm-derive",
  "cosmwasm-schema",
  "cosmwasm-std",
@@ -1339,7 +1350,7 @@ dependencies = [
 name = "nym-mixnet-contract-common"
 version = "0.6.0"
 dependencies = [
- "bs58",
+ "bs58 0.4.0",
  "cosmwasm-schema",
  "cosmwasm-std",
  "cw2",
@@ -1374,7 +1385,7 @@ name = "nym-name-service"
 version = "0.1.0"
 dependencies = [
  "anyhow",
- "bs58",
+ "bs58 0.4.0",
  "cosmwasm-schema",
  "cosmwasm-std",
  "cw-controllers",
@@ -1421,7 +1432,7 @@ name = "nym-service-provider-directory"
 version = "0.1.0"
 dependencies = [
  "anyhow",
- "bs58",
+ "bs58 0.4.0",
  "cosmwasm-schema",
  "cosmwasm-std",
  "cw-controllers",
@@ -1608,9 +1619,9 @@ dependencies = [
 
 [[package]]
 name = "proc-macro2"
-version = "1.0.63"
+version = "1.0.78"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7b368fba921b0dce7e60f5e04ec15e565b3303972b42bcfde1d0713b881959eb"
+checksum = "e2422ad645d89c99f8f3e6b88a9fdeca7fabeac836b1002371c4367c8f984aae"
 dependencies = [
  "unicode-ident",
 ]
@@ -1646,9 +1657,9 @@ checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
 
 [[package]]
 name = "quote"
-version = "1.0.30"
+version = "1.0.35"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5907a1b7c277254a8b15170f6e7c97cfa60ee7872a3217663bb81151e48184bb"
+checksum = "291ec9ab5efd934aaf503a6466c5d5251535d108ee747472c3977cc5acc868ef"
 dependencies = [
  "proc-macro2",
 ]
@@ -1888,9 +1899,9 @@ checksum = "b97ed7a9823b74f99c7742f5336af7be5ecd3eeafcb1507d1fa93347b1d589b0"
 
 [[package]]
 name = "serde"
-version = "1.0.190"
+version = "1.0.196"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "91d3c334ca1ee894a2c6f6ad698fe8c435b76d504b13d436f0685d648d6d96f7"
+checksum = "870026e60fa08c69f064aa766c10f10b1d62db9ccd4d0abb206472bee0ce3b32"
 dependencies = [
  "serde_derive",
 ]
@@ -1906,13 +1917,13 @@ dependencies = [
 
 [[package]]
 name = "serde_derive"
-version = "1.0.190"
+version = "1.0.196"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "67c5609f394e5c2bd7fc51efda478004ea80ef42fee983d5c67a65e34f32c0e3"
+checksum = "33c85360c95e7d137454dc81d9a4ed2b8efd8fbe19cee57357b32b9771fccb67"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.32",
+ "syn 2.0.49",
 ]
 
 [[package]]
@@ -1945,7 +1956,7 @@ checksum = "bcec881020c684085e55a25f7fd888954d56609ef363479dc5a1305eb0d40cab"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.32",
+ "syn 2.0.49",
 ]
 
 [[package]]
@@ -2000,7 +2011,7 @@ dependencies = [
  "aes",
  "arrayref",
  "blake2",
- "bs58",
+ "bs58 0.4.0",
  "byteorder",
  "chacha",
  "curve25519-dalek",
@@ -2059,9 +2070,9 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "2.0.32"
+version = "2.0.49"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "239814284fd6f1a4ffe4ca893952cdd93c224b6a1571c9a9eadd670295c0c9e2"
+checksum = "915aea9e586f80826ee59f8453c1101f9d1c4b3964cd2460185ee8e299ada496"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -2098,7 +2109,7 @@ checksum = "49922ecae66cc8a249b77e68d1d0623c1b2c514f0060c27cdc68bd62a1219d35"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.32",
+ "syn 2.0.49",
 ]
 
 [[package]]
@@ -2447,5 +2458,5 @@ checksum = "ce36e65b0d2999d2aafac989fb249189a141aee1f53c612c1f37d72631959f69"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.32",
+ "syn 2.0.49",
 ]

contracts/Cargo.toml

@@ -34,6 +34,7 @@ incremental = false
 overflow-checks = true
 
 [workspace.dependencies]
+bs58 = "0.4.0"
 cosmwasm-crypto = "=1.3.0"
 cosmwasm-derive = "=1.3.0"
 cosmwasm-schema = "=1.3.0"
@@ -49,5 +50,6 @@ cw3-fixed-multisig = "=1.1.0"
 cw4 = "=1.1.0"
 cw20 = "=1.1.0"
 semver = "1.0.21"
+serde = "1.0.196"
 
 thiserror = "1.0.48"

contracts/coconut-dkg/Cargo.toml

@@ -30,7 +30,6 @@ thiserror = { workspace = true }
 cw-multi-test = { workspace = true }
 cw4-group = { path = "../multisig/cw4-group" }
 nym-group-contract-common = { path = "../../common/cosmwasm-smart-contracts/group-contract" }
-rusty-fork = "0.3"
 
 [features]
 schema-gen = ["nym-coconut-dkg-common/schema", "cosmwasm-schema"]

contracts/coconut-dkg/schema/nym-coconut-dkg.json

@@ -180,15 +180,11 @@
           "commit_dealings_chunk": {
             "type": "object",
             "required": [
-              "chunk",
-              "resharing"
+              "chunk"
             ],
             "properties": {
               "chunk": {
                 "$ref": "#/definitions/PartialContractDealing"
-              },
-              "resharing": {
-                "type": "boolean"
               }
             },
             "additionalProperties": false
@@ -249,10 +245,10 @@
       {
         "type": "object",
         "required": [
-          "surpassed_threshold"
+          "advance_epoch_state"
         ],
         "properties": {
-          "surpassed_threshold": {
+          "advance_epoch_state": {
             "type": "object",
             "additionalProperties": false
           }
@@ -262,10 +258,23 @@
       {
         "type": "object",
         "required": [
-          "advance_epoch_state"
+          "trigger_reset"
         ],
         "properties": {
-          "advance_epoch_state": {
+          "trigger_reset": {
+            "type": "object",
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
+      },
+      {
+        "type": "object",
+        "required": [
+          "trigger_resharing"
+        ],
+        "properties": {
+          "trigger_resharing": {
             "type": "object",
             "additionalProperties": false
           }
@@ -368,16 +377,45 @@
       {
         "type": "object",
         "required": [
-          "get_initial_dealers"
+          "can_advance_state"
         ],
         "properties": {
-          "get_initial_dealers": {
+          "can_advance_state": {
             "type": "object",
             "additionalProperties": false
           }
         },
         "additionalProperties": false
       },
+      {
+        "type": "object",
+        "required": [
+          "get_registered_dealer"
+        ],
+        "properties": {
+          "get_registered_dealer": {
+            "type": "object",
+            "required": [
+              "dealer_address"
+            ],
+            "properties": {
+              "dealer_address": {
+                "type": "string"
+              },
+              "epoch_id": {
+                "type": [
+                  "integer",
+                  "null"
+                ],
+                "format": "uint64",
+                "minimum": 0.0
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
+      },
       {
         "type": "object",
         "required": [
@@ -431,10 +469,10 @@
       {
         "type": "object",
         "required": [
-          "get_past_dealers"
+          "get_dealer_indices"
         ],
         "properties": {
-          "get_past_dealers": {
+          "get_dealer_indices": {
             "type": "object",
             "properties": {
               "limit": {
@@ -716,6 +754,215 @@
   },
   "sudo": null,
   "responses": {
+    "can_advance_state": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "title": "StateAdvanceResponse",
+      "type": "object",
+      "required": [
+        "current_state",
+        "is_complete",
+        "progress",
+        "reached_deadline"
+      ],
+      "properties": {
+        "current_state": {
+          "$ref": "#/definitions/EpochState"
+        },
+        "deadline": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/Timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "is_complete": {
+          "type": "boolean"
+        },
+        "progress": {
+          "$ref": "#/definitions/StateProgress"
+        },
+        "reached_deadline": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false,
+      "definitions": {
+        "EpochState": {
+          "oneOf": [
+            {
+              "type": "string",
+              "enum": [
+                "waiting_initialisation",
+                "in_progress"
+              ]
+            },
+            {
+              "type": "object",
+              "required": [
+                "public_key_submission"
+              ],
+              "properties": {
+                "public_key_submission": {
+                  "type": "object",
+                  "required": [
+                    "resharing"
+                  ],
+                  "properties": {
+                    "resharing": {
+                      "type": "boolean"
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "required": [
+                "dealing_exchange"
+              ],
+              "properties": {
+                "dealing_exchange": {
+                  "type": "object",
+                  "required": [
+                    "resharing"
+                  ],
+                  "properties": {
+                    "resharing": {
+                      "type": "boolean"
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "required": [
+                "verification_key_submission"
+              ],
+              "properties": {
+                "verification_key_submission": {
+                  "type": "object",
+                  "required": [
+                    "resharing"
+                  ],
+                  "properties": {
+                    "resharing": {
+                      "type": "boolean"
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "required": [
+                "verification_key_validation"
+              ],
+              "properties": {
+                "verification_key_validation": {
+                  "type": "object",
+                  "required": [
+                    "resharing"
+                  ],
+                  "properties": {
+                    "resharing": {
+                      "type": "boolean"
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "required": [
+                "verification_key_finalization"
+              ],
+              "properties": {
+                "verification_key_finalization": {
+                  "type": "object",
+                  "required": [
+                    "resharing"
+                  ],
+                  "properties": {
+                    "resharing": {
+                      "type": "boolean"
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "StateProgress": {
+          "type": "object",
+          "required": [
+            "registered_dealers",
+            "registered_resharing_dealers",
+            "submitted_dealings",
+            "submitted_key_shares",
+            "verified_keys"
+          ],
+          "properties": {
+            "registered_dealers": {
+              "description": "Counts the number of dealers that have registered in this epoch.",
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            },
+            "registered_resharing_dealers": {
+              "description": "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.",
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            },
+            "submitted_dealings": {
+              "description": "Counts the number of fully received dealings (i.e. full chunks) from all the allowed dealers.",
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            },
+            "submitted_key_shares": {
+              "description": "Counts the number of submitted verification key shared from the dealers.",
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            },
+            "verified_keys": {
+              "description": "Counts the number of verified key shares.",
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            }
+          },
+          "additionalProperties": false
+        },
+        "Timestamp": {
+          "description": "A point in time in nanosecond precision.\n\nThis type can represent times from 1970-01-01T00:00:00Z to 2554-07-21T23:34:33Z.\n\n## Examples\n\n``` # use cosmwasm_std::Timestamp; let ts = Timestamp::from_nanos(1_000_000_202); assert_eq!(ts.nanos(), 1_000_000_202); assert_eq!(ts.seconds(), 1); assert_eq!(ts.subsec_nanos(), 202);\n\nlet ts = ts.plus_seconds(2); assert_eq!(ts.nanos(), 3_000_000_202); assert_eq!(ts.seconds(), 3); assert_eq!(ts.subsec_nanos(), 202); ```",
+          "allOf": [
+            {
+              "$ref": "#/definitions/Uint64"
+            }
+          ]
+        },
+        "Uint64": {
+          "description": "A thin wrapper around u64 that is using strings for JSON encoding/decoding, such that the full u64 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq.\n\n# Examples\n\nUse `from` to create instances of this and `u64` to get the value out:\n\n``` # use cosmwasm_std::Uint64; let a = Uint64::from(42u64); assert_eq!(a.u64(), 42);\n\nlet b = Uint64::from(70u32); assert_eq!(b.u64(), 70); ```",
+          "type": "string"
+        }
+      }
+    },
     "get_c_w2_contract_version": {
       "$schema": "http://json-schema.org/draft-07/schema#",
       "title": "ContractVersion",
@@ -813,15 +1060,11 @@
       "required": [
         "epoch_id",
         "state",
+        "state_progress",
         "time_configuration"
       ],
       "properties": {
-        "epoch_id": {
-          "type": "integer",
-          "format": "uint64",
-          "minimum": 0.0
-        },
-        "finish_timestamp": {
+        "deadline": {
           "anyOf": [
             {
               "$ref": "#/definitions/Timestamp"
@@ -831,9 +1074,17 @@
             }
           ]
         },
+        "epoch_id": {
+          "type": "integer",
+          "format": "uint64",
+          "minimum": 0.0
+        },
         "state": {
           "$ref": "#/definitions/EpochState"
         },
+        "state_progress": {
+          "$ref": "#/definitions/StateProgress"
+        },
         "time_configuration": {
           "$ref": "#/definitions/TimeConfiguration"
         }
@@ -956,6 +1207,49 @@
             }
           ]
         },
+        "StateProgress": {
+          "type": "object",
+          "required": [
+            "registered_dealers",
+            "registered_resharing_dealers",
+            "submitted_dealings",
+            "submitted_key_shares",
+            "verified_keys"
+          ],
+          "properties": {
+            "registered_dealers": {
+              "description": "Counts the number of dealers that have registered in this epoch.",
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            },
+            "registered_resharing_dealers": {
+              "description": "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.",
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            },
+            "submitted_dealings": {
+              "description": "Counts the number of fully received dealings (i.e. full chunks) from all the allowed dealers.",
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            },
+            "submitted_key_shares": {
+              "description": "Counts the number of submitted verification key shared from the dealers.",
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            },
+            "verified_keys": {
+              "description": "Counts the number of verified key shares.",
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            }
+          },
+          "additionalProperties": false
+        },
         "TimeConfiguration": {
           "type": "object",
           "required": [
@@ -1154,15 +1448,109 @@
           "additionalProperties": false
         },
         "DealerType": {
-          "type": "string",
-          "enum": [
-            "current",
-            "past",
-            "unknown"
+          "oneOf": [
+            {
+              "type": "string",
+              "enum": [
+                "unknown"
+              ]
+            },
+            {
+              "type": "object",
+              "required": [
+                "current"
+              ],
+              "properties": {
+                "current": {
+                  "type": "object",
+                  "required": [
+                    "assigned_index"
+                  ],
+                  "properties": {
+                    "assigned_index": {
+                      "type": "integer",
+                      "format": "uint64",
+                      "minimum": 0.0
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "required": [
+                "past"
+              ],
+              "properties": {
+                "past": {
+                  "type": "object",
+                  "required": [
+                    "assigned_index"
+                  ],
+                  "properties": {
+                    "assigned_index": {
+                      "type": "integer",
+                      "format": "uint64",
+                      "minimum": 0.0
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "additionalProperties": false
+            }
           ]
         }
       }
     },
+    "get_dealer_indices": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "title": "PagedDealerIndexResponse",
+      "type": "object",
+      "required": [
+        "indices"
+      ],
+      "properties": {
+        "indices": {
+          "type": "array",
+          "items": {
+            "type": "array",
+            "items": [
+              {
+                "$ref": "#/definitions/Addr"
+              },
+              {
+                "type": "integer",
+                "format": "uint64",
+                "minimum": 0.0
+              }
+            ],
+            "maxItems": 2,
+            "minItems": 2
+          }
+        },
+        "start_next_after": {
+          "description": "Field indicating paging information for the following queries if the caller wishes to get further entries.",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/Addr"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false,
+      "definitions": {
+        "Addr": {
+          "description": "A human readable address.\n\nIn Cosmos, this is typically bech32 encoded. But for multi-chain smart contracts no assumptions should be made other than being UTF-8 encoded and of reasonable length.\n\nThis type represents a validated address. It can be created in the following ways 1. Use `Addr::unchecked(input)` 2. Use `let checked: Addr = deps.api.addr_validate(input)?` 3. Use `let checked: Addr = deps.api.addr_humanize(canonical_addr)?` 4. Deserialize from JSON. This must only be done from JSON that was validated before such as a contract's state. `Addr` must not be used in messages sent by the user because this would result in unvalidated instances.\n\nThis type is immutable. If you really need to mutate it (Really? Are you sure?), create a mutable copy using `let mut mutable = Addr::to_string()` and operate on that `String` instance.",
+          "type": "string"
+        }
+      }
+    },
     "get_dealing_chunk": {
       "$schema": "http://json-schema.org/draft-07/schema#",
       "title": "DealingChunkResponse",
@@ -1455,70 +1843,15 @@
         }
       }
     },
-    "get_initial_dealers": {
+    "get_registered_dealer": {
       "$schema": "http://json-schema.org/draft-07/schema#",
-      "title": "Nullable_InitialReplacementData",
-      "anyOf": [
-        {
-          "$ref": "#/definitions/InitialReplacementData"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "definitions": {
-        "Addr": {
-          "description": "A human readable address.\n\nIn Cosmos, this is typically bech32 encoded. But for multi-chain smart contracts no assumptions should be made other than being UTF-8 encoded and of reasonable length.\n\nThis type represents a validated address. It can be created in the following ways 1. Use `Addr::unchecked(input)` 2. Use `let checked: Addr = deps.api.addr_validate(input)?` 3. Use `let checked: Addr = deps.api.addr_humanize(canonical_addr)?` 4. Deserialize from JSON. This must only be done from JSON that was validated before such as a contract's state. `Addr` must not be used in messages sent by the user because this would result in unvalidated instances.\n\nThis type is immutable. If you really need to mutate it (Really? Are you sure?), create a mutable copy using `let mut mutable = Addr::to_string()` and operate on that `String` instance.",
-          "type": "string"
-        },
-        "InitialReplacementData": {
-          "type": "object",
-          "required": [
-            "initial_dealers",
-            "initial_height"
-          ],
-          "properties": {
-            "initial_dealers": {
-              "type": "array",
-              "items": {
-                "$ref": "#/definitions/Addr"
-              }
-            },
-            "initial_height": {
-              "type": "integer",
-              "format": "uint64",
-              "minimum": 0.0
-            }
-          },
-          "additionalProperties": false
-        }
-      }
-    },
-    "get_past_dealers": {
-      "$schema": "http://json-schema.org/draft-07/schema#",
-      "title": "PagedDealerResponse",
+      "title": "RegisteredDealerDetails",
       "type": "object",
-      "required": [
-        "dealers",
-        "per_page"
-      ],
       "properties": {
-        "dealers": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/DealerDetails"
-          }
-        },
-        "per_page": {
-          "type": "integer",
-          "format": "uint",
-          "minimum": 0.0
-        },
-        "start_next_after": {
-          "description": "Field indicating paging information for the following queries if the caller wishes to get further entries.",
+        "details": {
           "anyOf": [
             {
-              "$ref": "#/definitions/Addr"
+              "$ref": "#/definitions/DealerRegistrationDetails"
             },
             {
               "type": "null"
@@ -1528,31 +1861,17 @@
       },
       "additionalProperties": false,
       "definitions": {
-        "Addr": {
-          "description": "A human readable address.\n\nIn Cosmos, this is typically bech32 encoded. But for multi-chain smart contracts no assumptions should be made other than being UTF-8 encoded and of reasonable length.\n\nThis type represents a validated address. It can be created in the following ways 1. Use `Addr::unchecked(input)` 2. Use `let checked: Addr = deps.api.addr_validate(input)?` 3. Use `let checked: Addr = deps.api.addr_humanize(canonical_addr)?` 4. Deserialize from JSON. This must only be done from JSON that was validated before such as a contract's state. `Addr` must not be used in messages sent by the user because this would result in unvalidated instances.\n\nThis type is immutable. If you really need to mutate it (Really? Are you sure?), create a mutable copy using `let mut mutable = Addr::to_string()` and operate on that `String` instance.",
-          "type": "string"
-        },
-        "DealerDetails": {
+        "DealerRegistrationDetails": {
           "type": "object",
           "required": [
-            "address",
             "announce_address",
-            "assigned_index",
             "bte_public_key_with_proof",
             "ed25519_identity"
           ],
           "properties": {
-            "address": {
-              "$ref": "#/definitions/Addr"
-            },
             "announce_address": {
               "type": "string"
             },
-            "assigned_index": {
-              "type": "integer",
-              "format": "uint64",
-              "minimum": 0.0
-            },
             "bte_public_key_with_proof": {
               "type": "string"
             },

contracts/coconut-dkg/schema/raw/execute.json

@@ -91,15 +91,11 @@
         "commit_dealings_chunk": {
           "type": "object",
           "required": [
-            "chunk",
-            "resharing"
+            "chunk"
           ],
           "properties": {
             "chunk": {
               "$ref": "#/definitions/PartialContractDealing"
-            },
-            "resharing": {
-              "type": "boolean"
             }
           },
           "additionalProperties": false
@@ -160,10 +156,10 @@
     {
       "type": "object",
       "required": [
-        "surpassed_threshold"
+        "advance_epoch_state"
       ],
       "properties": {
-        "surpassed_threshold": {
+        "advance_epoch_state": {
           "type": "object",
           "additionalProperties": false
         }
@@ -173,10 +169,23 @@
     {
       "type": "object",
       "required": [
-        "advance_epoch_state"
+        "trigger_reset"
       ],
       "properties": {
-        "advance_epoch_state": {
+        "trigger_reset": {
+          "type": "object",
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "required": [
+        "trigger_resharing"
+      ],
+      "properties": {
+        "trigger_resharing": {
           "type": "object",
           "additionalProperties": false
         }

contracts/coconut-dkg/schema/raw/query.json

@@ -44,16 +44,45 @@
     {
       "type": "object",
       "required": [
-        "get_initial_dealers"
+        "can_advance_state"
       ],
       "properties": {
-        "get_initial_dealers": {
+        "can_advance_state": {
           "type": "object",
           "additionalProperties": false
         }
       },
       "additionalProperties": false
     },
+    {
+      "type": "object",
+      "required": [
+        "get_registered_dealer"
+      ],
+      "properties": {
+        "get_registered_dealer": {
+          "type": "object",
+          "required": [
+            "dealer_address"
+          ],
+          "properties": {
+            "dealer_address": {
+              "type": "string"
+            },
+            "epoch_id": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "format": "uint64",
+              "minimum": 0.0
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     {
       "type": "object",
       "required": [
@@ -107,10 +136,10 @@
     {
       "type": "object",
       "required": [
-        "get_past_dealers"
+        "get_dealer_indices"
       ],
       "properties": {
-        "get_past_dealers": {
+        "get_dealer_indices": {
           "type": "object",
           "properties": {
             "limit": {

contracts/coconut-dkg/schema/raw/response_to_can_advance_state.json

@@ -0,0 +1,209 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "StateAdvanceResponse",
+  "type": "object",
+  "required": [
+    "current_state",
+    "is_complete",
+    "progress",
+    "reached_deadline"
+  ],
+  "properties": {
+    "current_state": {
+      "$ref": "#/definitions/EpochState"
+    },
+    "deadline": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/Timestamp"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "is_complete": {
+      "type": "boolean"
+    },
+    "progress": {
+      "$ref": "#/definitions/StateProgress"
+    },
+    "reached_deadline": {
+      "type": "boolean"
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "EpochState": {
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": [
+            "waiting_initialisation",
+            "in_progress"
+          ]
+        },
+        {
+          "type": "object",
+          "required": [
+            "public_key_submission"
+          ],
+          "properties": {
+            "public_key_submission": {
+              "type": "object",
+              "required": [
+                "resharing"
+              ],
+              "properties": {
+                "resharing": {
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": [
+            "dealing_exchange"
+          ],
+          "properties": {
+            "dealing_exchange": {
+              "type": "object",
+              "required": [
+                "resharing"
+              ],
+              "properties": {
+                "resharing": {
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": [
+            "verification_key_submission"
+          ],
+          "properties": {
+            "verification_key_submission": {
+              "type": "object",
+              "required": [
+                "resharing"
+              ],
+              "properties": {
+                "resharing": {
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": [
+            "verification_key_validation"
+          ],
+          "properties": {
+            "verification_key_validation": {
+              "type": "object",
+              "required": [
+                "resharing"
+              ],
+              "properties": {
+                "resharing": {
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": [
+            "verification_key_finalization"
+          ],
+          "properties": {
+            "verification_key_finalization": {
+              "type": "object",
+              "required": [
+                "resharing"
+              ],
+              "properties": {
+                "resharing": {
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "StateProgress": {
+      "type": "object",
+      "required": [
+        "registered_dealers",
+        "registered_resharing_dealers",
+        "submitted_dealings",
+        "submitted_key_shares",
+        "verified_keys"
+      ],
+      "properties": {
+        "registered_dealers": {
+          "description": "Counts the number of dealers that have registered in this epoch.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0.0
+        },
+        "registered_resharing_dealers": {
+          "description": "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.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0.0
+        },
+        "submitted_dealings": {
+          "description": "Counts the number of fully received dealings (i.e. full chunks) from all the allowed dealers.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0.0
+        },
+        "submitted_key_shares": {
+          "description": "Counts the number of submitted verification key shared from the dealers.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0.0
+        },
+        "verified_keys": {
+          "description": "Counts the number of verified key shares.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0.0
+        }
+      },
+      "additionalProperties": false
+    },
+    "Timestamp": {
+      "description": "A point in time in nanosecond precision.\n\nThis type can represent times from 1970-01-01T00:00:00Z to 2554-07-21T23:34:33Z.\n\n## Examples\n\n``` # use cosmwasm_std::Timestamp; let ts = Timestamp::from_nanos(1_000_000_202); assert_eq!(ts.nanos(), 1_000_000_202); assert_eq!(ts.seconds(), 1); assert_eq!(ts.subsec_nanos(), 202);\n\nlet ts = ts.plus_seconds(2); assert_eq!(ts.nanos(), 3_000_000_202); assert_eq!(ts.seconds(), 3); assert_eq!(ts.subsec_nanos(), 202); ```",
+      "allOf": [
+        {
+          "$ref": "#/definitions/Uint64"
+        }
+      ]
+    },
+    "Uint64": {
+      "description": "A thin wrapper around u64 that is using strings for JSON encoding/decoding, such that the full u64 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq.\n\n# Examples\n\nUse `from` to create instances of this and `u64` to get the value out:\n\n``` # use cosmwasm_std::Uint64; let a = Uint64::from(42u64); assert_eq!(a.u64(), 42);\n\nlet b = Uint64::from(70u32); assert_eq!(b.u64(), 70); ```",
+      "type": "string"
+    }
+  }
+}

contracts/coconut-dkg/schema/raw/response_to_get_current_epoch_state.json

@@ -5,15 +5,11 @@
   "required": [
     "epoch_id",
     "state",
+    "state_progress",
     "time_configuration"
   ],
   "properties": {
-    "epoch_id": {
-      "type": "integer",
-      "format": "uint64",
-      "minimum": 0.0
-    },
-    "finish_timestamp": {
+    "deadline": {
       "anyOf": [
         {
           "$ref": "#/definitions/Timestamp"
@@ -23,9 +19,17 @@
         }
       ]
     },
+    "epoch_id": {
+      "type": "integer",
+      "format": "uint64",
+      "minimum": 0.0
+    },
     "state": {
       "$ref": "#/definitions/EpochState"
     },
+    "state_progress": {
+      "$ref": "#/definitions/StateProgress"
+    },
     "time_configuration": {
       "$ref": "#/definitions/TimeConfiguration"
     }
@@ -148,6 +152,49 @@
         }
       ]
     },
+    "StateProgress": {
+      "type": "object",
+      "required": [
+        "registered_dealers",
+        "registered_resharing_dealers",
+        "submitted_dealings",
+        "submitted_key_shares",
+        "verified_keys"
+      ],
+      "properties": {
+        "registered_dealers": {
+          "description": "Counts the number of dealers that have registered in this epoch.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0.0
+        },
+        "registered_resharing_dealers": {
+          "description": "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.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0.0
+        },
+        "submitted_dealings": {
+          "description": "Counts the number of fully received dealings (i.e. full chunks) from all the allowed dealers.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0.0
+        },
+        "submitted_key_shares": {
+          "description": "Counts the number of submitted verification key shared from the dealers.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0.0
+        },
+        "verified_keys": {
+          "description": "Counts the number of verified key shares.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0.0
+        }
+      },
+      "additionalProperties": false
+    },
     "TimeConfiguration": {
       "type": "object",
       "required": [