Revert "Remove rustls feature on workspace deps (#4422 )"

This reverts commit 2bff66e2c7.
Bump ip in /clients/native/examples/js-examples/websocket (#4421 )
2024-03-06 12:39:36 +02:00 · 2024-03-06 08:15:03 +01:00 · 2024-03-06 07:58:31 +01:00 · 2024-03-05 15:07:38 +00:00 · 2024-03-04 14:48:43 +01:00 · 2024-03-04 12:19:41 +00:00
51 changed files with 852 additions and 450 deletions
@@ -5128,6 +5128,7 @@ dependencies = [
 "nym-credentials",
 "nym-credentials-interface",
 "nym-crypto",
+ "nym-id",
 "nym-mixnet-contract-common",
 "nym-multisig-contract-common",
 "nym-name-service-common",
@@ -5168,6 +5169,7 @@ dependencies = [
 "nym-credentials",
 "nym-crypto",
 "nym-gateway-requests",
+ "nym-id",
 "nym-network-defaults",
 "nym-pemstore",
 "nym-sphinx",
@@ -5626,6 +5628,32 @@ dependencies = [
 "serde",
 ]

+[[package]]
+name = "nym-id"
+version = "0.1.0"
+dependencies = [
+ "nym-credential-storage",
+ "nym-credentials",
+ "thiserror",
+ "time",
+ "tracing",
+ "zeroize",
+]
+
+[[package]]
+name = "nym-id-cli"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "bs58 0.5.0",
+ "clap 4.4.7",
+ "nym-bin-common",
+ "nym-credential-storage",
+ "nym-id",
+ "tokio",
+ "tracing",
+]
+
 [[package]]
 name = "nym-inclusion-probability"
 version = "0.1.0"
@@ -5864,6 +5892,7 @@ dependencies = [
 "nym-credentials",
 "nym-crypto",
 "nym-exit-policy",
+ "nym-id",
 "nym-network-defaults",
 "nym-ordered-buffer",
 "nym-sdk",
@@ -6151,6 +6180,7 @@ dependencies = [
 "nym-credentials",
 "nym-crypto",
 "nym-gateway-requests",
+ "nym-id",
 "nym-network-defaults",
 "nym-ordered-buffer",
 "nym-pemstore",
@@ -56,6 +56,7 @@ members = [
    "common/node-tester-utils",
    "common/nonexhaustive-delayqueue",
    "common/nymcoconut",
+    "common/nym-id",
    "common/nymsphinx",
    "common/nymsphinx/acknowledgements",
    "common/nymsphinx/addressing",
@@ -106,6 +107,7 @@ members = [
    "tools/internal/ssl-inject",
    # "tools/internal/sdk-version-bump",
    "tools/nym-cli",
+    "tools/nym-id-cli",
    "tools/nym-nr-query",
    "tools/nymvisor",
    "tools/ts-rs-cli",
@@ -51,5 +51,6 @@ nym-task = { path = "../../common/task" }
 nym-topology = { path = "../../common/topology" }
 nym-validator-client = { path = "../../common/client-libs/validator-client", features = ["http-client"] }
 nym-client-websocket-requests = { path = "websocket-requests" }
+nym-id = { path = "../../common/nym-id" }

 [dev-dependencies]
@@ -2160,9 +2160,9 @@
      }
    },
    "node_modules/ip": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/ip/-/ip-1.1.5.tgz",
-      "integrity": "sha1-vd7XARQpCCjAoDnnLvJfWq7ENUo=",
+      "version": "1.1.9",
+      "resolved": "https://registry.npmjs.org/ip/-/ip-1.1.9.tgz",
+      "integrity": "sha512-cyRxvOEpNHNtchU3Ln9KC/auJgup87llfQpQ+t5ghoC/UhL16SWzbueiCsdTnWmqAWl7LadfuwhlqmtOaqMHdQ==",
      "dev": true
    },
    "node_modules/ipaddr.js": {
@@ -6157,9 +6157,9 @@
      "dev": true
    },
    "ip": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/ip/-/ip-1.1.5.tgz",
-      "integrity": "sha1-vd7XARQpCCjAoDnnLvJfWq7ENUo=",
+      "version": "1.1.9",
+      "resolved": "https://registry.npmjs.org/ip/-/ip-1.1.9.tgz",
+      "integrity": "sha512-cyRxvOEpNHNtchU3Ln9KC/auJgup87llfQpQ+t5ghoC/UhL16SWzbueiCsdTnWmqAWl7LadfuwhlqmtOaqMHdQ==",
      "dev": true
    },
    "ipaddr.js": {
@@ -4,14 +4,10 @@
 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 nym_id::import_credential;
 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()
@@ -33,8 +29,8 @@ pub(crate) struct Args {
    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,
+    #[clap(long, hide = true)]
+    pub(crate) version: Option<u8>,
 }

 pub(crate) async fn execute(args: Args) -> Result<(), ClientError> {
@@ -52,50 +48,7 @@ pub(crate) async fn execute(args: Args) -> Result<(), ClientError> {
            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?;
+    import_credential(credentials_store, raw_credential, args.version).await?;
    Ok(())
 }
@@ -1,6 +1,6 @@
 use nym_client_core::error::ClientCoreError;
-use nym_credential_storage::error::StorageError;
-use time::OffsetDateTime;
+
+use nym_id::NymIdError;

 #[derive(thiserror::Error, Debug)]
 pub enum ClientError {
@@ -23,21 +23,6 @@ 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 },
+    #[error(transparent)]
+    NymIdError(#[from] NymIdError),
 }
@@ -35,6 +35,7 @@ nym-ordered-buffer = { path = "../../common/socks5/ordered-buffer" }
 nym-pemstore = { path = "../../common/pemstore" }
 nym-topology = { path = "../../common/topology" }
 nym-socks5-client-core = { path = "../../common/socks5-client-core" }
+nym-id = { path = "../../common/nym-id" }

 [features]
 default = []
@@ -4,14 +4,10 @@
 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 nym_id::import_credential;
 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()
@@ -33,8 +29,8 @@ pub(crate) struct Args {
    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,
+    #[clap(long, hide = true)]
+    pub(crate) version: Option<u8>,
 }

 pub(crate) async fn execute(args: Args) -> Result<(), Socks5ClientError> {
@@ -52,50 +48,7 @@ pub(crate) async fn execute(args: Args) -> Result<(), Socks5ClientError> {
            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?;
+    import_credential(credentials_store, raw_credential, args.version).await?;
    Ok(())
 }
@@ -1,6 +1,6 @@
 use nym_client_core::error::ClientCoreError;
-use nym_credential_storage::error::StorageError;
-use time::OffsetDateTime;
+
+use nym_id::NymIdError;

 #[derive(thiserror::Error, Debug)]
 pub enum Socks5ClientError {
@@ -23,21 +23,6 @@ pub enum Socks5ClientError {
    #[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 },
+    #[error(transparent)]
+    NymIdError(#[from] NymIdError),
 }
@@ -69,6 +69,35 @@ impl BinaryBuildInformation {
        }
    }

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

-#[cfg(not(target_arch = "wasm32"))]
+#[cfg(unix)]
 use std::os::fd::RawFd;
 #[cfg(not(target_arch = "wasm32"))]
 use tokio::time::sleep;
 #[cfg(not(target_arch = "wasm32"))]
 use tokio_tungstenite::connect_async;

-#[cfg(target_arch = "wasm32")]
+#[cfg(not(unix))]
 use std::os::raw::c_int as RawFd;
 #[cfg(target_arch = "wasm32")]
 use wasm_utils::websocket::JSWebsocket;
@@ -15,7 +15,7 @@ use std::os::raw::c_int as RawFd;
 use std::sync::Arc;
 use tungstenite::Message;

-#[cfg(not(target_arch = "wasm32"))]
+#[cfg(unix)]
 use std::os::fd::AsRawFd;
 #[cfg(not(target_arch = "wasm32"))]
 use tokio::net::TcpStream;
@@ -41,14 +41,14 @@ 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"))]
+    #[cfg(unix)]
    match _conn.get_ref() {
        MaybeTlsStream::Plain(stream) => Some(stream.as_raw_fd()),
        &_ => unreachable!(
            "If tls features are enabled, the inner stream needs to be unpacked into raw fd"
        ),
    }
-    #[cfg(target_arch = "wasm32")]
+    #[cfg(not(unix))]
    None
 }

@@ -55,6 +55,7 @@ nym-credentials = { path = "../../common/credentials" }
 nym-credentials-interface = { path = "../../common/credentials-interface" }
 nym-credential-storage = { path = "../../common/credential-storage" }
 nym-credential-utils = { path = "../../common/credential-utils" }
+nym-id = { path = "../nym-id" }

 nym-pemstore = { path = "../../common/pemstore", version = "0.3.0" }
 nym-types = { path = "../../common/types" }
@@ -5,15 +5,10 @@ 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 nym_id::import_credential;
 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()
@@ -35,8 +30,8 @@ pub struct Args {
    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,
+    #[clap(long, hide = true)]
+    pub(crate) version: Option<u8>,
 }

 pub async fn execute(args: Args) -> anyhow::Result<()> {
@@ -54,6 +49,7 @@ pub async fn execute(args: Args) -> anyhow::Result<()> {
        "using credentials store at '{}'",
        credentials_store.display()
    );
+    let credentials_store = initialise_persistent_storage(credentials_store).await;

    let raw_credential = match args.credential_data {
        Some(data) => data,
@@ -62,44 +58,7 @@ pub async fn execute(args: Args) -> anyhow::Result<()> {
            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?;
+    import_credential(credentials_store, raw_credential, args.version).await?;
    Ok(())
 }
@@ -315,9 +315,12 @@ impl IssuanceBandwidthCredential {
    }

    // TODO: is that actually needed?
+    // idea: make it consistent with the issued credential and its vX serde
    pub fn try_from_recovered_bytes(bytes: &[u8]) -> Result<Self, Error> {
        use bincode::Options;
-        Ok(make_recovery_bincode_serializer().deserialize(bytes)?)
+        make_recovery_bincode_serializer()
+            .deserialize(bytes)
+            .map_err(|source| Error::RecoveryCredentialDeserializationFailure { source })
    }
 }

@@ -327,3 +330,18 @@ fn make_recovery_bincode_serializer() -> impl bincode::Options {
        .with_big_endian()
        .with_varint_encoding()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn assert_zeroize_on_drop<T: ZeroizeOnDrop>() {}
+
+    fn assert_zeroize<T: Zeroize>() {}
+
+    #[test]
+    fn credential_is_zeroized() {
+        assert_zeroize::<IssuanceBandwidthCredential>();
+        assert_zeroize_on_drop::<IssuanceBandwidthCredential>();
+    }
+}
@@ -116,6 +116,15 @@ impl IssuedBandwidthCredential {
        }
    }

+    pub fn try_unpack(bytes: &[u8], revision: impl Into<Option<u8>>) -> Result<Self, Error> {
+        let revision = revision.into().unwrap_or(CURRENT_SERIALIZATION_REVISION);
+
+        match revision {
+            1 => Self::unpack_v1(bytes),
+            _ => Err(Error::UnknownSerializationRevision { revision }),
+        }
+    }
+
    pub fn epoch_id(&self) -> EpochId {
        self.epoch_id
    }
@@ -138,7 +147,12 @@ impl IssuedBandwidthCredential {
    /// Unpack (deserialize) the credential data from the given bytes using v1 serializer.
    pub fn unpack_v1(bytes: &[u8]) -> Result<Self, Error> {
        use bincode::Options;
-        Ok(make_storable_bincode_serializer().deserialize(bytes)?)
+        make_storable_bincode_serializer()
+            .deserialize(bytes)
+            .map_err(|source| Error::SerializationFailure {
+                source,
+                revision: 1,
+            })
    }

    pub fn randomise_signature(&mut self) {
@@ -191,3 +205,18 @@ fn make_storable_bincode_serializer() -> impl bincode::Options {
        .with_big_endian()
        .with_varint_encoding()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn assert_zeroize_on_drop<T: ZeroizeOnDrop>() {}
+
+    fn assert_zeroize<T: Zeroize>() {}
+
+    #[test]
+    fn credential_is_zeroized() {
+        assert_zeroize::<IssuedBandwidthCredential>();
+        assert_zeroize_on_drop::<IssuedBandwidthCredential>();
+    }
+}
@@ -5,6 +5,7 @@ use nym_credentials_interface::CoconutError;
 use nym_crypto::asymmetric::encryption::KeyRecoveryError;
 use nym_validator_client::ValidatorClientError;

+use crate::coconut::bandwidth::issued::CURRENT_SERIALIZATION_REVISION;
 use thiserror::Error;

 #[derive(Debug, Error)]
@@ -12,8 +13,18 @@ pub enum Error {
    #[error("IO error")]
    IOError(#[from] std::io::Error),

-    #[error("failed to (de)serialize credential structure: {0}")]
-    SerializationFailure(#[from] bincode::Error),
+    #[error("failed to deserialize a recovery credential: {source}")]
+    RecoveryCredentialDeserializationFailure { source: bincode::Error },
+
+    #[error("failed to (de)serialize provided credential using revision {revision}: {source}")]
+    SerializationFailure {
+        #[source]
+        source: bincode::Error,
+        revision: u8,
+    },
+
+    #[error("unknown credential serializatio revision {revision}. the current (and max supported) version is {CURRENT_SERIALIZATION_REVISION}")]
+    UnknownSerializationRevision { revision: u8 },

    #[error("The detailed description is yet to be determined")]
    BandwidthCredentialError,
@@ -9,3 +9,4 @@ pub use coconut::bandwidth::{
    IssuedBandwidthCredential,
 };
 pub use coconut::utils::{obtain_aggregate_signature, obtain_aggregate_verification_key};
+pub use error::Error;
@@ -1,8 +1,32 @@
+use serde::{Deserialize, Serialize};
+use std::fmt::{Display, Formatter};
+use std::net::{Ipv4Addr, Ipv6Addr};
+
 pub mod codec;
 pub mod request;
 pub mod response;

-pub const CURRENT_VERSION: u8 = 3;
+// version 3: initial version
+// version 4: IPv6 support
+pub const CURRENT_VERSION: u8 = 4;
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub struct IpPair {
+    pub ipv4: Ipv4Addr,
+    pub ipv6: Ipv6Addr,
+}
+
+impl IpPair {
+    pub fn new(ipv4: Ipv4Addr, ipv6: Ipv6Addr) -> Self {
+        IpPair { ipv4, ipv6 }
+    }
+}
+
+impl Display for IpPair {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        writeln!(f, "IPv4: {}, IPV6: {}", self.ipv4, self.ipv6)
+    }
+}

 fn make_bincode_serializer() -> impl bincode::Options {
    use bincode::Options;
@@ -1,9 +1,7 @@
-use std::net::IpAddr;
-
 use nym_sphinx::addressing::clients::Recipient;
 use serde::{Deserialize, Serialize};

-use crate::{make_bincode_serializer, CURRENT_VERSION};
+use crate::{make_bincode_serializer, IpPair, CURRENT_VERSION};

 fn generate_random() -> u64 {
    use rand::RngCore;
@@ -19,7 +17,7 @@ pub struct IpPacketRequest {

 impl IpPacketRequest {
    pub fn new_static_connect_request(
-        ip: IpAddr,
+        ips: IpPair,
        reply_to: Recipient,
        reply_to_hops: Option<u8>,
        reply_to_avg_mix_delays: Option<f64>,
@@ -31,7 +29,7 @@ impl IpPacketRequest {
                version: CURRENT_VERSION,
                data: IpPacketRequestData::StaticConnect(StaticConnectRequest {
                    request_id,
-                    ip,
+                    ips,
                    reply_to,
                    reply_to_hops,
                    reply_to_avg_mix_delays,
@@ -137,7 +135,7 @@ pub enum IpPacketRequestData {
 pub struct StaticConnectRequest {
    pub request_id: u64,

-    pub ip: IpAddr,
+    pub ips: IpPair,

    // The nym-address the response should be sent back to
    pub reply_to: Recipient,
@@ -210,6 +208,8 @@ pub struct HealthRequest {
 #[cfg(test)]
 mod tests {
    use super::*;
+    use std::net::{Ipv4Addr, Ipv6Addr};
+    use std::str::FromStr;

    #[test]
    fn check_size_of_request() {
@@ -218,15 +218,15 @@ mod tests {
            data: IpPacketRequestData::StaticConnect(
                StaticConnectRequest {
                    request_id: 123,
-                    ip: IpAddr::from([10, 0, 0, 1]),
+                    ips: IpPair::new(Ipv4Addr::from_str("10.0.0.1").unwrap(), Ipv6Addr::from_str("2001:db8:a160::1").unwrap()),
                    reply_to: Recipient::try_from_base58_string("D1rrpsysCGCYXy9saP8y3kmNpGtJZUXN9SvFoUcqAsM9.9Ssso1ea5NfkbMASdiseDSjTN1fSWda5SgEVjdSN4CvV@GJqd3ZxpXWSNxTfx7B1pPtswpetH4LnJdFeLeuY5KUuN").unwrap(),
                    reply_to_hops: None,
                    reply_to_avg_mix_delays: None,
                    buffer_timeout: None,
                },
-            )
+            ),
        };
-        assert_eq!(connect.to_bytes().unwrap().len(), 108);
+        assert_eq!(connect.to_bytes().unwrap().len(), 123);
    }

    #[test]
@@ -1,9 +1,7 @@
-use std::net::IpAddr;
-
 use nym_sphinx::addressing::clients::Recipient;
 use serde::{Deserialize, Serialize};

-use crate::{make_bincode_serializer, CURRENT_VERSION};
+use crate::{make_bincode_serializer, IpPair, CURRENT_VERSION};

 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct IpPacketResponse {
@@ -38,13 +36,13 @@ impl IpPacketResponse {
        }
    }

-    pub fn new_dynamic_connect_success(request_id: u64, reply_to: Recipient, ip: IpAddr) -> Self {
+    pub fn new_dynamic_connect_success(request_id: u64, reply_to: Recipient, ips: IpPair) -> Self {
        Self {
            version: CURRENT_VERSION,
            data: IpPacketResponseData::DynamicConnect(DynamicConnectResponse {
                request_id,
                reply_to,
-                reply: DynamicConnectResponseReply::Success(DynamicConnectSuccess { ip }),
+                reply: DynamicConnectResponseReply::Success(DynamicConnectSuccess { ips }),
            }),
        }
    }
@@ -263,7 +261,7 @@ impl DynamicConnectResponseReply {

 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct DynamicConnectSuccess {
-    pub ip: IpAddr,
+    pub ips: IpPair,
 }

 #[derive(Clone, Debug, Serialize, Deserialize, thiserror::Error)]
@@ -0,0 +1,20 @@
+[package]
+name = "nym-id"
+version = "0.1.0"
+authors.workspace = true
+repository.workspace = true
+homepage.workspace = true
+documentation.workspace = true
+edition.workspace = true
+license.workspace = true
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+thiserror.workspace = true
+time.workspace = true
+tracing.workspace = true
+zeroize.workspace = true
+
+nym-credential-storage = { path = "../credential-storage" }
+nym-credentials = { path = "../credentials" }
@@ -0,0 +1,20 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use std::error::Error;
+use thiserror::Error;
+use time::OffsetDateTime;
+
+#[derive(Debug, Error)]
+pub enum NymIdError {
+    #[error("failed to deserialize provided credential: {source}")]
+    CredentialDeserializationFailure { source: nym_credentials::Error },
+
+    #[error("attempted to import an expired credential (it expired on {expiration})")]
+    ExpiredCredentialImport { expiration: OffsetDateTime },
+
+    #[error("failed to store credential in the provided store: {source}")]
+    StorageError {
+        source: Box<dyn Error + Send + Sync>,
+    },
+}
@@ -0,0 +1,71 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::NymIdError;
+use nym_credential_storage::models::StorableIssuedCredential;
+use nym_credential_storage::storage::Storage;
+use nym_credentials::coconut::bandwidth::issued::BandwidthCredentialIssuedDataVariant;
+use nym_credentials::IssuedBandwidthCredential;
+use tracing::{debug, warn};
+use zeroize::Zeroizing;
+
+pub async fn import_credential<S>(
+    credentials_store: S,
+    raw_credential: Vec<u8>,
+    credential_version: impl Into<Option<u8>>,
+) -> Result<(), NymIdError>
+where
+    S: Storage,
+    <S as Storage>::StorageError: Send + Sync + 'static,
+{
+    let raw_credential = Zeroizing::new(raw_credential);
+
+    // note: the type itself implements ZeroizeOnDrop
+    let credential = IssuedBandwidthCredential::try_unpack(&raw_credential, credential_version)
+        .map_err(|source| NymIdError::CredentialDeserializationFailure { source })?;
+
+    debug!(
+        "attempting to import credential of type {}",
+        credential.typ()
+    );
+
+    match credential.variant_data() {
+        BandwidthCredentialIssuedDataVariant::Voucher(voucher_info) => {
+            debug!("with value of {}", voucher_info.value())
+        }
+        BandwidthCredentialIssuedDataVariant::FreePass(freepass_info) => {
+            debug!("with expiry at {}", freepass_info.expiry_date());
+            if freepass_info.expired() {
+                warn!("the free pass has already expired!");
+
+                // technically we can import it, but the gateway will just reject it so what's the point
+                return Err(NymIdError::ExpiredCredentialImport {
+                    expiration: freepass_info.expiry_date(),
+                });
+            }
+        }
+    }
+
+    // SAFETY:
+    // for the epoch to run over u32::MAX, we'd have to advance it for few centuries every block...
+    // the alternative is a very particularly malformed serialized data, but at that point blowing up is the right call
+    // because we can't rely on it anyway
+    #[allow(clippy::expect_used)]
+    let storable = StorableIssuedCredential {
+        serialization_revision: credential.current_serialization_revision(),
+        credential_data: &raw_credential,
+        credential_type: credential.typ().to_string(),
+        epoch_id: credential
+            .epoch_id()
+            .try_into()
+            .expect("our epoch is has run over u32::MAX!"),
+    };
+
+    credentials_store
+        .insert_issued_credential(storable)
+        .await
+        .map_err(|source| NymIdError::StorageError {
+            source: Box::new(source),
+        })?;
+    Ok(())
+}
@@ -0,0 +1,11 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+#![warn(clippy::expect_used)]
+#![warn(clippy::unwrap_used)]
+
+pub mod error;
+pub mod import_credential;
+
+pub use error::NymIdError;
+pub use import_credential::import_credential;
@@ -1,3 +1,4 @@
+use std::net::Ipv6Addr;
 use std::{
    collections::HashMap,
    net::{IpAddr, Ipv4Addr},
@@ -19,6 +20,12 @@ const TUN_WRITE_TIMEOUT_MS: u64 = 1000;

 #[derive(thiserror::Error, Debug)]
 pub enum TunDeviceError {
+    #[error("{0}")]
+    IO(#[from] std::io::Error),
+
+    #[error("{0}")]
+    TokioTun(#[from] tokio_tun::Error),
+
    #[error("timeout writing to tun device, dropping packet")]
    TunWriteTimeout,

@@ -44,14 +51,18 @@ pub enum TunDeviceError {
    FailedToLockPeer,
 }

-fn setup_tokio_tun_device(name: &str, address: Ipv4Addr, netmask: Ipv4Addr) -> tokio_tun::Tun {
+fn setup_tokio_tun_device(
+    name: &str,
+    address: Ipv4Addr,
+    netmask: Ipv4Addr,
+) -> Result<tokio_tun::Tun, TunDeviceError> {
    log::info!("Creating TUN device with: address={address}, netmask={netmask}");
    // Read MTU size from env variable NYM_MTU_SIZE, else default to 1420.
    let mtu = std::env::var("NYM_MTU_SIZE")
        .map(|mtu| mtu.parse().expect("NYM_MTU_SIZE must be a valid integer"))
        .unwrap_or(1420);
    log::info!("Using MTU size: {mtu}");
-    tokio_tun::Tun::builder()
+    Ok(tokio_tun::Tun::builder()
        .name(name)
        .tap(false)
        .packet_info(false)
@@ -59,8 +70,7 @@ fn setup_tokio_tun_device(name: &str, address: Ipv4Addr, netmask: Ipv4Addr) -> t
        .up()
        .address(address)
        .netmask(netmask)
-        .try_build()
-        .expect("Failed to setup tun device, do you have permission?")
+        .try_build()?)
 }

 pub struct TunDevice {
@@ -103,16 +113,18 @@ pub struct NatInner {

 pub struct TunDeviceConfig {
    pub base_name: String,
-    pub ip: Ipv4Addr,
-    pub netmask: Ipv4Addr,
+    pub ipv4: Ipv4Addr,
+    pub netmaskv4: Ipv4Addr,
+    pub ipv6: Ipv6Addr,
+    pub netmaskv6: String,
 }

 impl TunDevice {
    pub fn new(
        routing_mode: RoutingMode,
        config: TunDeviceConfig,
-    ) -> (Self, TunTaskTx, TunTaskResponseRx) {
-        let tun = Self::new_device_only(config);
+    ) -> Result<(Self, TunTaskTx, TunTaskResponseRx), TunDeviceError> {
+        let tun = Self::new_device_only(config)?;

        // Channels to communicate with the other tasks
        let (tun_task_tx, tun_task_rx) = tun_task_channel();
@@ -125,20 +137,32 @@ impl TunDevice {
            routing_mode,
        };

-        (tun_device, tun_task_tx, tun_task_response_rx)
+        Ok((tun_device, tun_task_tx, tun_task_response_rx))
    }

-    pub fn new_device_only(config: TunDeviceConfig) -> tokio_tun::Tun {
+    pub fn new_device_only(config: TunDeviceConfig) -> Result<tokio_tun::Tun, TunDeviceError> {
        let TunDeviceConfig {
            base_name,
-            ip,
-            netmask,
+            ipv4,
+            netmaskv4,
+            ipv6,
+            netmaskv6,
        } = config;
        let name = format!("{base_name}%d");

-        let tun = setup_tokio_tun_device(&name, ip, netmask);
+        let tun = setup_tokio_tun_device(&name, ipv4, netmaskv4)?;
        log::info!("Created TUN device: {}", tun.name());
-        tun
+        std::process::Command::new("ip")
+            .args([
+                "-6",
+                "addr",
+                "add",
+                &format!("{}/{}", ipv6, netmaskv6),
+                "dev",
+                &tun.name(),
+            ])
+            .output()?;
+        Ok(tun)
    }

    // Send outbound packets out on the wild internet
@@ -1,7 +1,7 @@
 [book]
-title = "Nym Docs"
+title = "Nym Operators Guide"
 authors = ["Max Hampshire, Serinko, Alexia Lorenza Martinel"]
-description = "Nym technical documentation"
+description = "Everything needed to run Nym Mixnet components"
 language = "en"
 multilingual = false # for the moment - ideally work on chinese, brazillian portugese, spanish next
 src = "src"
@@ -31,7 +31,7 @@ assets_version = "3.0.0" # do not edit: managed by `mdbook-admonish install`
 minimum_rust_version = "1.66"
 wallet_release_version = "1.2.8"
 # nym-vpn related variables
-nym_vpn_latest_binary_url = "https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.3"
+nym_vpn_latest_binary_url = "https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.4"
 nym_vpn_form_url = "https://opnform.com/forms/nymvpn-user-research-at-37c3-yccqko-2"

 [preprocessor.last-changed]
@@ -44,6 +44,9 @@ renderer = ["html"]
 # more pre-processor plugins to look into from https://github.com/rust-lang/mdBook/wiki/Third-party-plugins & https://lib.rs/keywords/mdbook-preprocessor
 # mdbook-i18n

+# [preprocessor.api-call]
+# command = "$(tokens=$(curl -L https://api.nymtech.net/cosmos/staking/v1beta1/pool | jq 'values[\"pool\"][\"bonded_tokens\"]') && echo ${tokens:0:2},${tokens:2:2})"
+
 #########
 # BUILD #
 #########
@@ -23,6 +23,12 @@
  - [Automatic Node Upgrade: Nymvisor Setup and Usage](nodes/nymvisor-upgrade.md)
 - [Troubleshooting](nodes/troubleshooting.md)

+# Token Economics
+
+<!-- - [Fair Mixnet](tokenomics/fair-mixnet.md) -->
+<!--    - [Mixnet: Nym Node Rewards](tokenomics/mixnet-rewards.md) -->
+- [Nyx: Validator Rewards](tokenomics/validator-rewards.md)
+
 # FAQ

 - [Mix Nodes](faq/mixnodes-faq.md)
@@ -23,7 +23,7 @@ systemctl start <NODE>.service
 journalctl -f -u <NODE>.service # to monitor log of you node
 ```

-If these steps are too difficult and you prefer to just run a script, you can use [ExploreNYM script](https://github.com/ExploreNYM/bash-tool) or one done by [Nym developers](https://gist.github.com/tommyv1987/4dca7cc175b70742c9ecb3d072eb8539).
+If these steps are too difficult and you prefer to automate the process, try to setup your flow with [Nymvisor](nymvisor-upgrade.md).

 > In case of a Network Requester this is all, the following step is only for Mix Nodes and Gateways.

@@ -98,4 +98,3 @@ The most common reason for your validator being jailed is that your validator is
 Running the command `df -H` will return the size of the various partitions of your VPS.

 If the `/dev/sda` partition is almost full, try pruning some of the `.gz` syslog archives and restart your validator process.
-
@@ -0,0 +1,7 @@
+#!/bin/bash
+
+stake_unyx=$(curl -s -L https://api.nymtech.net/cosmos/staking/v1beta1/pool | jq 'values["pool"]["bonded_tokens"]')
+stake_unyx=$(python -c "print(int($stake_unyx))")
+stake_nyx=$(python -c "print($stake_unyx / 1000000)")
+voting288k_percent=$(python -c "print(288000 / $stake_nyx * 100)")
+echo ${voting288k_percent:0:4}%
@@ -0,0 +1,4 @@
+#!/bin/bash
+
+stake=$(curl -s -L https://api.nymtech.net/cosmos/staking/v1beta1/pool | jq 'values["pool"]["bonded_tokens"]')
+echo ${stake:1:2}.${stake:3:3}
@@ -0,0 +1,55 @@
+# Nyx Validator Rewards
+
+## Summary
+
+* Nyx Validators are rewarded in NYM tokens from the Nym mixmining pool and increasingly from apps that run on the Nym mixnet, the first of which is the NymVPN.
+* Validators are rewarded for two different types of work: signing blocks in the Nyx chain and running the NymAPI to monitor mixnet routing and sign zk-nym credentials.
+* New validators can join via a NYM-to-NYX swap contract. The contract will not allow more than 1% of total stake increase per month to prevent sudden hostile takeovers. Current stake is <!-- cmdrun ../scripts/nyx-total-stake.sh --> million Nyx. Rate: 1:4.8 ~ 288k NYX for 60k NYM => <!-- cmdrun ../scripts/nyx-percent-stake.sh --> voting power
+* NYX tokens serve no other purpose than self-delegation for voting power and governance. All rewards are in NYM and distributed directly to the validators self-delegation address and are not distributed to stakers.
+* The contract will only allow swapping NYM to NYX and will **not** allow exchanging NYX back to NYM. A NYX holder who wishes to sell their NYX stake will have to do so via OTC trades.
+
+## Validator Rewards
+
+Nyx Validators perform two types of work for which they will be rewarded:
+
+### 1. Signing blocks in the Nyx chain
+
+A “block signing monitor" monitors blocks being produced on the Nyx chain and gathers the signatures present on every block. After an epoch ends, the monitor will assess performance of a validator and distribute tokens (to the self-delegation wallet) proportional to the voting period and uptime of the validator.
+
+### 2. Running the NymAPI to monitor Mixnet routing and sign zk-nyms (Nym’s anonymous credentials)
+
+Validator rewards initially come from the Nym mixmining pool with additional rewards increasingly coming from paid applications running on the Nym mixnet. The first paid application is the NymVPN. Nyx validators will be rewarded for their work directly in NYM tokens to their validator self-delegation address.
+
+1. **From mixmining pool** - at a rate of 1000 NYM per hour, of which 2/3 are distributed for signing blocks and 1/3 for zk-nyms. These are stable in NYM, and therefore will fluctuate in their fiat value depending on exchange rate.
+
+2. **From vpn user subscriptions** - the rate is tied to the growth of NymVPN subscriptions and will be stable in fiat, fluctuating in NYM depending on exchange rate. 1/3 will be distributed for signing blocks and 2/3 for zk-nyms. 
+
+| Source         | Signing blocks | Running NymAPI | Currency |
+| :--            | --:           | --:    | :---:    |
+| Mixmining pool | 2/3           | 1/3    | NYM      |
+| NymVPN         | 1/3           | 2/3    | fiat     |
+
+#### zk-nyms
+
+The zk-nyms enable people to anonymously prove access rights to the upcoming NymVPN client without having to reveal payment details that might compromise their privacy. This is the first of what we imagine to be many possible use-cases for the zk-nym scheme.
+
+### Allocation of Rewards from Nym mixmining pool
+
+Rewards for validators will be distributed at an hourly rate from the mixmining pool. The amount is 1000 NYM per hour to be distributed among all validators. The fraction of mixmining rewards received by each individual validator is proportional to its contributions to the network.
+
+Two thirds of the available rewards (670 NYM per hour) are distributed proportionally to each validator’s share when signing blocks in the chain, for which tx fees are also received in the same proportion; while the last third (330 NYM per hour) is allocated to validators running the NymAPI, proportionally to their contribution to signing zk-nym credentials.
+
+The rewards are stable in NYM and fluctuate in their fiat value depending on the exchange rate of NYM tokens.
+
+## Permissionless Nyx Chain
+
+To allow new validators to join Nyx chain a new smart contract will be set up to release NYX in exchange for NYM. This contract allows a limited amount of NYM tokens to be deposited per month. The deposited NYM tokens are added to the mixmining pool and thus contribute to future rewards of all nodes and validators.
+
+The smart contract will have two parameters:
+
+1. the maximum amount of NYX available for purchase per month
+2. the NYM-to-NYX exchange rate offered by the contract
+
+### Maximum Amount of NYX Available for Purchase per Month
+
+The contract will not allow more than 1% of total stake increase per month to prevent sudden hostile takeovers. Current stake level is <!-- cmdrun ../scripts/nyx-total-stake.sh --> million Nyx.
@@ -1,7 +1,7 @@
 import React, { FC } from 'react';
 import { ChainProvider, useChain } from '@cosmos-kit/react';
 import { assets, chains } from 'chain-registry';
-import { wallets as keplr } from '@cosmos-kit/keplr';
+import { wallets as keplr } from '@cosmos-kit/keplr-extension';
 import { wallets as ledger } from '@cosmos-kit/ledger';
 import Button from '@mui/material/Button';
 import CircularProgress from '@mui/material/CircularProgress';
@@ -12,16 +12,17 @@
    "start": "next start"
  },
  "dependencies": {
-    "@cosmjs/amino": "^0.31.1",
+    "@cosmjs/amino": "^0.32.2",
    "@cosmjs/cosmwasm-launchpad": "^0.25.6",
-    "@cosmjs/cosmwasm-stargate": "^0.31.1",
-    "@cosmjs/encoding": "^0.31.1",
-    "@cosmjs/proto-signing": "^0.31.1",
-    "@cosmjs/stargate": "^0.31.0",
-    "@cosmos-kit/core": "^2.6.2",
-    "@cosmos-kit/keplr": "^2.3.9",
-    "@cosmos-kit/ledger": "^2.4.3",
-    "@cosmos-kit/react": "^2.8.0",
+    "@cosmjs/cosmwasm-stargate": "^0.32.2",
+    "@cosmjs/encoding": "^0.32.2",
+    "@cosmjs/proto-signing": "^0.32.2",
+    "@cosmjs/stargate": "^0.32.2",
+    "@cosmos-kit/core": "^2.8.9",
+    "@cosmos-kit/keplr": "^2.6.9",
+    "@cosmos-kit/keplr-extension": "^2.7.9",
+    "@cosmos-kit/ledger": "^2.6.9",
+    "@cosmos-kit/react": "^2.10.11",
    "@emotion/react": "^11.11.1",
    "@emotion/styled": "^11.11.0",
    "@interchain-ui/react": "^1.8.0",
@@ -32,7 +33,7 @@
    "@nymproject/mix-fetch-full-fat": ">=1.2.4-rc.2 || ^1",
    "@nymproject/sdk-full-fat": ">=1.2.4-rc.2 || ^1",
    "chain-registry": "^1.19.0",
-    "cosmjs-types": "^0.8.0",
+    "cosmjs-types": "^0.9.0",
    "next": "^13.4.19",
    "nextra": "latest",
    "nextra-theme-docs": "latest",
@@ -32,7 +32,6 @@ If you're unsure where to start, the following set of questions should help you

 ### Use one of our standalone Nym clients
 If you've answered 'No' to all of the above, you may need to use one of our [standalone clients](https://nymtech.net/docs/clients/overview.html). All Nym client packages present basically the same capabilities to the privacy application developer. They need to run as a persistent process in order to stay connected and ready to receive any incoming messages from their gateway nodes. They register and authenticate to gateways, and construct Sphinx packets. While setting up those, and depending on your usecase, you may need to set-up and run a Service Provider. Read below the "How to deal with Service Providers" section for more details.
- You can find more information about the different standalone clients and the ways to interact with them [in this page](https://nymtech.net/developers/integrations/mixnet-integration.html). 



@@ -1,9 +1,13 @@
+use std::net::{Ipv4Addr, Ipv6Addr};
 use std::time::Duration;

 // The interface used to route traffic
 pub const TUN_BASE_NAME: &str = "nymtun";
-pub const TUN_DEVICE_ADDRESS: &str = "10.0.0.1";
-pub const TUN_DEVICE_NETMASK: &str = "255.255.255.0";
+pub const TUN_DEVICE_ADDRESS_V4: Ipv4Addr = Ipv4Addr::new(10, 0, 0, 1);
+pub const TUN_DEVICE_NETMASK_V4: Ipv4Addr = Ipv4Addr::new(255, 255, 255, 0);
+pub const TUN_DEVICE_ADDRESS_V6: Ipv6Addr = Ipv6Addr::new(0x2001, 0xdb8, 0xa160, 0, 0, 0, 0, 0x1); // 2001:db8:a160::1
+
+pub const TUN_DEVICE_NETMASK_V6: &str = "120";

 // We routinely check if any clients needs to be disconnected at this interval
 pub(crate) const DISCONNECT_TIMER_INTERVAL: Duration = Duration::from_secs(10);
@@ -11,6 +11,10 @@ pub enum IpPacketRouterError {
    #[error("client-core error: {0}")]
    ClientCoreError(#[from] ClientCoreError),

+    #[cfg(target_os = "linux")]
+    #[error("tun device error: {0}")]
+    TunDeviceError(#[from] nym_tun::tun_device::TunDeviceError),
+
    #[error("failed to load configuration file: {0}")]
    FailedToLoadConfig(String),

@@ -133,11 +133,13 @@ impl IpPacketRouter {
        // Create the TUN device that we interact with the rest of the world with
        let config = nym_tun::tun_device::TunDeviceConfig {
            base_name: crate::constants::TUN_BASE_NAME.to_string(),
-            ip: crate::constants::TUN_DEVICE_ADDRESS.parse().unwrap(),
-            netmask: crate::constants::TUN_DEVICE_NETMASK.parse().unwrap(),
+            ipv4: crate::constants::TUN_DEVICE_ADDRESS_V4,
+            netmaskv4: crate::constants::TUN_DEVICE_NETMASK_V4,
+            ipv6: crate::constants::TUN_DEVICE_ADDRESS_V6,
+            netmaskv6: crate::constants::TUN_DEVICE_NETMASK_V6.to_string(),
        };
        let (tun_reader, tun_writer) =
-            tokio::io::split(nym_tun::tun_device::TunDevice::new_device_only(config));
+            tokio::io::split(nym_tun::tun_device::TunDevice::new_device_only(config)?);

        // Channel used by the IpPacketRouter to signal connected and disconnected clients to the
        // TunListener
@@ -1,7 +1,6 @@
-use std::{
-    collections::HashMap,
-    net::{IpAddr, SocketAddr},
-};
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+use std::sync::Arc;
+use std::{collections::HashMap, net::SocketAddr};

 use bytes::{Bytes, BytesMut};
 use futures::StreamExt;
@@ -12,6 +11,7 @@ use nym_ip_packet_requests::{
        DynamicConnectFailureReason, ErrorResponseReply, IpPacketResponse,
        StaticConnectFailureReason,
    },
+    IpPair,
 };
 use nym_sdk::mixnet::{MixnetMessageSender, Recipient};
 use nym_sphinx::receiver::ReconstructedMessage;
@@ -19,6 +19,7 @@ use nym_task::TaskHandle;
 use tap::TapFallible;
 #[cfg(target_os = "linux")]
 use tokio::io::AsyncWriteExt;
+use tokio::sync::RwLock;
 use tokio_util::codec::Decoder;

 use crate::{
@@ -37,7 +38,8 @@ use crate::{

 pub(crate) struct ConnectedClients {
    // The set of connected clients
-    clients: HashMap<IpAddr, ConnectedClient>,
+    clients_ipv4_mapping: HashMap<Ipv4Addr, ConnectedClient>,
+    clients_ipv6_mapping: HashMap<Ipv6Addr, ConnectedClient>,

    // Notify the tun listener when a new client connects or disconnects
    tun_listener_connected_client_tx: tokio::sync::mpsc::UnboundedSender<ConnectedClientEvent>,
@@ -48,46 +50,59 @@ impl ConnectedClients {
        let (connected_client_tx, connected_client_rx) = tokio::sync::mpsc::unbounded_channel();
        (
            Self {
-                clients: Default::default(),
+                clients_ipv4_mapping: Default::default(),
+                clients_ipv6_mapping: Default::default(),
                tun_listener_connected_client_tx: connected_client_tx,
            },
            tun_listener::ConnectedClientsListener::new(connected_client_rx),
        )
    }

-    fn is_ip_connected(&self, ip: &IpAddr) -> bool {
-        self.clients.contains_key(ip)
+    fn is_ip_connected(&self, ips: &IpPair) -> bool {
+        self.clients_ipv4_mapping.contains_key(&ips.ipv4)
+            || self.clients_ipv6_mapping.contains_key(&ips.ipv6)
    }

    fn get_client_from_ip_mut(&mut self, ip: &IpAddr) -> Option<&mut ConnectedClient> {
-        self.clients.get_mut(ip)
+        match ip {
+            IpAddr::V4(ip) => self.clients_ipv4_mapping.get_mut(ip),
+            IpAddr::V6(ip) => self.clients_ipv6_mapping.get_mut(ip),
+        }
    }

    fn is_nym_address_connected(&self, nym_address: &Recipient) -> bool {
-        self.clients
+        self.clients_ipv4_mapping
            .values()
            .any(|client| client.nym_address == *nym_address)
    }

-    fn lookup_ip_from_nym_address(&self, nym_address: &Recipient) -> Option<IpAddr> {
-        self.clients.iter().find_map(|(ip, client)| {
-            if client.nym_address == *nym_address {
-                Some(*ip)
-            } else {
-                None
-            }
-        })
+    fn lookup_ip_from_nym_address(&self, nym_address: &Recipient) -> Option<IpPair> {
+        self.clients_ipv4_mapping
+            .iter()
+            .find_map(|(ipv4, connected_client)| {
+                if connected_client.nym_address == *nym_address {
+                    Some(IpPair::new(*ipv4, connected_client.ipv6))
+                } else {
+                    None
+                }
+            })
    }

    fn lookup_client_from_nym_address(&self, nym_address: &Recipient) -> Option<&ConnectedClient> {
-        self.clients
-            .values()
-            .find(|client| client.nym_address == *nym_address)
+        self.clients_ipv4_mapping
+            .iter()
+            .find_map(|(_, connected_client)| {
+                if connected_client.nym_address == *nym_address {
+                    Some(connected_client)
+                } else {
+                    None
+                }
+            })
    }

    fn connect(
        &mut self,
-        ip: IpAddr,
+        ips: IpPair,
        nym_address: Recipient,
        mix_hops: Option<u8>,
        forward_from_tun_tx: tokio::sync::mpsc::UnboundedSender<Vec<u8>>,
@@ -96,21 +111,25 @@ impl ConnectedClients {
    ) {
        // The map of connected clients that the mixnet listener keeps track of. It monitors
        // activity and disconnects clients that have been inactive for too long.
-        self.clients.insert(
-            ip,
-            ConnectedClient {
+        let client = ConnectedClient {
+            nym_address,
+            ipv6: ips.ipv6,
+            mix_hops,
+            last_activity: Arc::new(RwLock::new(std::time::Instant::now())),
+            _close_tx: Arc::new(CloseTx {
                nym_address,
-                mix_hops,
-                last_activity: std::time::Instant::now(),
-                close_tx: Some(close_tx),
-                handle,
-            },
-        );
+                inner: Some(close_tx),
+            }),
+            handle: Arc::new(handle),
+        };
+        log::info!("Inserting {} and {}", ips.ipv4, ips.ipv6);
+        self.clients_ipv4_mapping.insert(ips.ipv4, client.clone());
+        self.clients_ipv6_mapping.insert(ips.ipv6, client);
        // Send the connected client info to the tun listener, which will use it to forward packets
        // to the connected client handler.
        self.tun_listener_connected_client_tx
            .send(ConnectedClientEvent::Connect(Box::new(ConnectEvent {
-                ip,
+                ips,
                forward_from_tun_tx,
            })))
            .tap_err(|err| {
@@ -119,9 +138,9 @@ impl ConnectedClients {
            .ok();
    }

-    fn update_activity(&mut self, ip: &IpAddr) -> Result<()> {
-        if let Some(client) = self.clients.get_mut(ip) {
-            client.last_activity = std::time::Instant::now();
+    async fn update_activity(&mut self, ips: &IpPair) -> Result<()> {
+        if let Some(client) = self.clients_ipv4_mapping.get(&ips.ipv4) {
+            *client.last_activity.write().await = std::time::Instant::now();
            Ok(())
        } else {
            Err(IpPacketRouterError::FailedToUpdateClientActivity)
@@ -129,12 +148,15 @@ impl ConnectedClients {
    }

    // Identify connected client handlers that have stopped without being told to stop
-    fn get_finished_client_handlers(&mut self) -> Vec<(IpAddr, Recipient)> {
-        self.clients
+    fn get_finished_client_handlers(&mut self) -> Vec<(IpPair, Recipient)> {
+        self.clients_ipv4_mapping
            .iter_mut()
-            .filter_map(|(ip, client)| {
-                if client.handle.is_finished() {
-                    Some((*ip, client.nym_address))
+            .filter_map(|(ip, connected_client)| {
+                if connected_client.handle.is_finished() {
+                    Some((
+                        IpPair::new(*ip, connected_client.ipv6),
+                        connected_client.nym_address,
+                    ))
                } else {
                    None
                }
@@ -142,26 +164,29 @@ impl ConnectedClients {
            .collect()
    }

-    fn get_inactive_clients(&mut self) -> Vec<(IpAddr, Recipient)> {
+    async fn get_inactive_clients(&mut self) -> Vec<(IpPair, Recipient)> {
        let now = std::time::Instant::now();
-        self.clients
-            .iter()
-            .filter_map(|(ip, client)| {
-                if now.duration_since(client.last_activity) > CLIENT_MIXNET_INACTIVITY_TIMEOUT {
-                    Some((*ip, client.nym_address))
-                } else {
-                    None
-                }
-            })
-            .collect()
+        let mut ret = vec![];
+        for (ip, connected_client) in self.clients_ipv4_mapping.iter() {
+            if now.duration_since(*connected_client.last_activity.read().await)
+                > CLIENT_MIXNET_INACTIVITY_TIMEOUT
+            {
+                ret.push((
+                    IpPair::new(*ip, connected_client.ipv6),
+                    connected_client.nym_address,
+                ))
+            }
+        }
+        ret
    }

-    fn disconnect_stopped_client_handlers(&mut self, stopped_clients: Vec<(IpAddr, Recipient)>) {
-        for (ip, _) in &stopped_clients {
-            log::info!("Disconnect stopped client: {ip}");
-            self.clients.remove(ip);
+    fn disconnect_stopped_client_handlers(&mut self, stopped_clients: Vec<(IpPair, Recipient)>) {
+        for (ips, _) in &stopped_clients {
+            log::info!("Disconnect stopped client: {ips}");
+            self.clients_ipv4_mapping.remove(&ips.ipv4);
+            self.clients_ipv6_mapping.remove(&ips.ipv6);
            self.tun_listener_connected_client_tx
-                .send(ConnectedClientEvent::Disconnect(DisconnectEvent(*ip)))
+                .send(ConnectedClientEvent::Disconnect(DisconnectEvent(*ips)))
                .tap_err(|err| {
                    log::error!("Failed to send disconnect event: {err}");
                })
@@ -169,12 +194,13 @@ impl ConnectedClients {
        }
    }

-    fn disconnect_inactive_clients(&mut self, inactive_clients: Vec<(IpAddr, Recipient)>) {
-        for (ip, _) in &inactive_clients {
-            log::info!("Disconnect inactive client: {ip}");
-            self.clients.remove(ip);
+    fn disconnect_inactive_clients(&mut self, inactive_clients: Vec<(IpPair, Recipient)>) {
+        for (ips, _) in &inactive_clients {
+            log::info!("Disconnect inactive client: {ips}");
+            self.clients_ipv4_mapping.remove(&ips.ipv4);
+            self.clients_ipv6_mapping.remove(&ips.ipv6);
            self.tun_listener_connected_client_tx
-                .send(ConnectedClientEvent::Disconnect(DisconnectEvent(*ip)))
+                .send(ConnectedClientEvent::Disconnect(DisconnectEvent(*ips)))
                .tap_err(|err| {
                    log::error!("Failed to send disconnect event: {err}");
                })
@@ -182,40 +208,49 @@ impl ConnectedClients {
        }
    }

-    fn find_new_ip(&self) -> Option<IpAddr> {
-        generate_new_ip::find_new_ip(&self.clients)
+    fn find_new_ip(&self) -> Option<IpPair> {
+        generate_new_ip::find_new_ips(&self.clients_ipv4_mapping, &self.clients_ipv6_mapping)
    }
 }

+pub(crate) struct CloseTx {
+    pub(crate) nym_address: Recipient,
+    // Send to connected clients listener to stop. This is option only because we need to take
+    // ownership of it when the client is dropped.
+    pub(crate) inner: Option<tokio::sync::oneshot::Sender<()>>,
+}
+
+#[derive(Clone)]
 pub(crate) struct ConnectedClient {
    // The nym address of the connected client that we are communicating with on the other side of
    // the mixnet
    pub(crate) nym_address: Recipient,

+    // The assigned IPv6 address of this client
+    pub(crate) ipv6: Ipv6Addr,
+
    // Number of mix node hops that the client has requested to use
    pub(crate) mix_hops: Option<u8>,

    // Keep track of last activity so we can disconnect inactive clients
-    pub(crate) last_activity: std::time::Instant,
+    pub(crate) last_activity: Arc<RwLock<std::time::Instant>>,

-    // Send to connected clients listener to stop. This is option only because we need to take
-    // ownership of it when the client is dropped.
-    pub(crate) close_tx: Option<tokio::sync::oneshot::Sender<()>>,
+    pub(crate) _close_tx: Arc<CloseTx>,

    // Handle for the connected client handler
-    pub(crate) handle: tokio::task::JoinHandle<()>,
+    pub(crate) handle: Arc<tokio::task::JoinHandle<()>>,
 }

 impl ConnectedClient {
-    fn update_activity(&mut self) {
-        self.last_activity = std::time::Instant::now();
+    async fn update_activity(&self) {
+        *self.last_activity.write().await = std::time::Instant::now();
    }
 }

-impl Drop for ConnectedClient {
+impl Drop for CloseTx {
    fn drop(&mut self) {
        log::debug!("signal to close client: {}", self.nym_address);
-        if let Some(close_tx) = self.close_tx.take() {
+        if let Some(close_tx) = self.inner.take() {
            close_tx.send(()).ok();
        }
    }
@@ -259,7 +294,7 @@ impl MixnetListener {
        );

        let request_id = connect_request.request_id;
-        let requested_ip = connect_request.ip;
+        let requested_ips = connect_request.ips;
        let reply_to = connect_request.reply_to;
        let reply_to_hops = connect_request.reply_to_hops;
        // TODO: add to connect request
@@ -267,7 +302,7 @@ impl MixnetListener {
        // TODO: ignoring reply_to_avg_mix_delays for now

        // Check that the IP is available in the set of connected clients
-        let is_ip_taken = self.connected_clients.is_ip_connected(&requested_ip);
+        let is_ip_taken = self.connected_clients.is_ip_connected(&requested_ips);

        // Check that the nym address isn't already registered
        let is_nym_address_taken = self.connected_clients.is_nym_address_connected(&reply_to);
@@ -277,7 +312,8 @@ impl MixnetListener {
                log::info!("Connecting an already connected client");
                if self
                    .connected_clients
-                    .update_activity(&requested_ip)
+                    .update_activity(&requested_ips)
+                    .await
                    .is_err()
                {
                    log::error!("Failed to update activity for client");
@@ -300,7 +336,7 @@ impl MixnetListener {

                // Register the new client in the set of connected clients
                self.connected_clients.connect(
-                    requested_ip,
+                    requested_ips,
                    reply_to,
                    reply_to_hops,
                    forward_from_tun_tx,
@@ -350,11 +386,12 @@ impl MixnetListener {
        // TODO: this is problematic. Until we sign connect requests this means you can spam people
        // with return traffic

-        if let Some(existing_ip) = self.connected_clients.lookup_ip_from_nym_address(&reply_to) {
+        if let Some(existing_ips) = self.connected_clients.lookup_ip_from_nym_address(&reply_to) {
            log::info!("Found existing client for nym address");
            if self
                .connected_clients
-                .update_activity(&existing_ip)
+                .update_activity(&existing_ips)
+                .await
                .is_err()
            {
                log::error!("Failed to update activity for client");
@@ -362,11 +399,11 @@ impl MixnetListener {
            return Ok(Some(IpPacketResponse::new_dynamic_connect_success(
                request_id,
                reply_to,
-                existing_ip,
+                existing_ips,
            )));
        }

-        let Some(new_ip) = self.connected_clients.find_new_ip() else {
+        let Some(new_ips) = self.connected_clients.find_new_ip() else {
            log::info!("No available IP address");
            return Ok(Some(IpPacketResponse::new_dynamic_connect_failure(
                request_id,
@@ -386,7 +423,7 @@ impl MixnetListener {

        // Register the new client in the set of connected clients
        self.connected_clients.connect(
-            new_ip,
+            new_ips,
            reply_to,
            reply_to_hops,
            forward_from_tun_tx,
@@ -394,7 +431,7 @@ impl MixnetListener {
            handle,
        );
        Ok(Some(IpPacketResponse::new_dynamic_connect_success(
-            request_id, reply_to, new_ip,
+            request_id, reply_to, new_ips,
        )))
    }

@@ -428,7 +465,7 @@ impl MixnetListener {

        if let Some(connected_client) = self.connected_clients.get_client_from_ip_mut(&src_addr) {
            // Keep track of activity so we can disconnect inactive clients
-            connected_client.update_activity();
+            connected_client.update_activity().await;

            // For packets without a port, use 0.
            let dst = dst.unwrap_or_else(|| SocketAddr::new(dst_addr, 0));
@@ -539,9 +576,9 @@ impl MixnetListener {
        }
    }

-    fn handle_disconnect_timer(&mut self) {
+    async fn handle_disconnect_timer(&mut self) {
        let stopped_clients = self.connected_clients.get_finished_client_handlers();
-        let inactive_clients = self.connected_clients.get_inactive_clients();
+        let inactive_clients = self.connected_clients.get_inactive_clients().await;

        // TODO: Send disconnect responses to all disconnected clients
        //for (ip, nym_address) in stopped_clients.iter().chain(disconnected_clients.iter()) {
@@ -571,10 +608,14 @@ impl MixnetListener {
        })?;

        // We could avoid this lookup if we check this when we create the response.
-        let mix_hops = self
+        let mix_hops = if let Some(c) = self
            .connected_clients
            .lookup_client_from_nym_address(recipient)
-            .and_then(|c| c.mix_hops);
+        {
+            c.mix_hops
+        } else {
+            None
+        };

        let input_message = create_input_message(*recipient, response_packet, mix_hops);
        self.mixnet_client
@@ -613,7 +654,7 @@ impl MixnetListener {
                    log::debug!("IpPacketRouter [main loop]: received shutdown");
                },
                _ = disconnect_timer.tick() => {
-                    self.handle_disconnect_timer();
+                    self.handle_disconnect_timer().await;
                },
                msg = self.mixnet_client.next() => {
                    if let Some(msg) = msg {
@@ -642,9 +683,9 @@ pub(crate) enum ConnectedClientEvent {
    Connect(Box<ConnectEvent>),
 }

-pub(crate) struct DisconnectEvent(pub(crate) IpAddr);
+pub(crate) struct DisconnectEvent(pub(crate) IpPair);

 pub(crate) struct ConnectEvent {
-    pub(crate) ip: IpAddr,
+    pub(crate) ips: IpPair,
    pub(crate) forward_from_tun_tx: tokio::sync::mpsc::UnboundedSender<Vec<u8>>,
 }
@@ -1,5 +1,7 @@
-use std::{collections::HashMap, net::IpAddr};
+use std::collections::HashMap;
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};

+use nym_ip_packet_requests::IpPair;
 use nym_task::TaskClient;
 #[cfg(target_os = "linux")]
 use tokio::io::AsyncReadExt;
@@ -15,10 +17,12 @@ use crate::{
 // It's even ok if this is slightly out of date
 pub(crate) struct ConnectedClientMirror {
    pub(crate) forward_from_tun_tx: tokio::sync::mpsc::UnboundedSender<Vec<u8>>,
+    pub(crate) ips: IpPair,
 }

 pub(crate) struct ConnectedClientsListener {
-    clients: HashMap<IpAddr, ConnectedClientMirror>,
+    clients_ipv4: HashMap<Ipv4Addr, ConnectedClientMirror>,
+    clients_ipv6: HashMap<Ipv6Addr, ConnectedClientMirror>,
    connected_client_rx:
        tokio::sync::mpsc::UnboundedReceiver<mixnet_listener::ConnectedClientEvent>,
 }
@@ -30,35 +34,48 @@ impl ConnectedClientsListener {
        >,
    ) -> Self {
        ConnectedClientsListener {
-            clients: HashMap::new(),
+            clients_ipv4: HashMap::new(),
+            clients_ipv6: HashMap::new(),
            connected_client_rx,
        }
    }

    pub(crate) fn get(&self, ip: &IpAddr) -> Option<&ConnectedClientMirror> {
-        self.clients.get(ip)
+        match ip {
+            IpAddr::V4(ip) => self.clients_ipv4.get(ip),
+            IpAddr::V6(ip) => self.clients_ipv6.get(ip),
+        }
    }

    pub(crate) fn update(&mut self, event: mixnet_listener::ConnectedClientEvent) {
        match event {
            mixnet_listener::ConnectedClientEvent::Connect(connected_event) => {
                let mixnet_listener::ConnectEvent {
-                    ip,
+                    ips,
                    forward_from_tun_tx,
                } = *connected_event;
-                log::trace!("Connect client: {ip}");
-                self.clients.insert(
-                    ip,
+                log::trace!("Connect client: {ips}");
+                self.clients_ipv4.insert(
+                    ips.ipv4,
+                    ConnectedClientMirror {
+                        forward_from_tun_tx: forward_from_tun_tx.clone(),
+                        ips,
+                    },
+                );
+                self.clients_ipv6.insert(
+                    ips.ipv6,
                    ConnectedClientMirror {
                        forward_from_tun_tx,
+                        ips,
                    },
                );
            }
            mixnet_listener::ConnectedClientEvent::Disconnect(
-                mixnet_listener::DisconnectEvent(ip),
+                mixnet_listener::DisconnectEvent(ips),
            ) => {
-                log::trace!("Disconnect client: {ip}");
-                self.clients.remove(&ip);
+                log::trace!("Disconnect client: {ips}");
+                self.clients_ipv4.remove(&ips.ipv4);
+                self.clients_ipv6.remove(&ips.ipv6);
            }
        }
    }
@@ -82,6 +99,7 @@ impl TunListener {

        if let Some(ConnectedClientMirror {
            forward_from_tun_tx,
+            ips,
        }) = self.connected_clients.get(&dst_addr)
        {
            let packet = buf[..len].to_vec();
@@ -89,7 +107,7 @@ impl TunListener {
                log::warn!("Failed to forward packet to connected client {dst_addr}: disconnecting it from tun listener");
                self.connected_clients
                    .update(mixnet_listener::ConnectedClientEvent::Disconnect(
-                        mixnet_listener::DisconnectEvent(dst_addr),
+                        mixnet_listener::DisconnectEvent(*ips),
                    ));
            }
        } else {
@@ -1,38 +1,52 @@
-use std::{
-    collections::HashMap,
-    net::{IpAddr, Ipv4Addr},
-};
+use nym_ip_packet_requests::IpPair;
+use std::net::Ipv6Addr;
+use std::{collections::HashMap, net::Ipv4Addr};

-use crate::{constants::TUN_DEVICE_ADDRESS, mixnet_listener::ConnectedClient};
+use crate::constants::{TUN_DEVICE_ADDRESS_V4, TUN_DEVICE_ADDRESS_V6};

 // Find an available IP address in self.connected_clients
 // TODO: make this nicer
-fn generate_random_ip_within_subnet() -> Ipv4Addr {
+fn generate_random_ips_within_subnet() -> IpPair {
    let mut rng = rand::thread_rng();
    // Generate a random number in the range 1-254
    let last_octet = rand::Rng::gen_range(&mut rng, 1..=254);
-    Ipv4Addr::new(10, 0, 0, last_octet)
+    let ipv4 = Ipv4Addr::new(10, 0, 0, last_octet);
+    let ipv6 = Ipv6Addr::new(0x2001, 0x0db8, 0xa160, 0, 0, 0, 0, last_octet as u16);
+    IpPair::new(ipv4, ipv6)
 }

-fn is_ip_taken(
-    connected_clients: &HashMap<IpAddr, ConnectedClient>,
-    tun_ip: Ipv4Addr,
-    ip: Ipv4Addr,
+fn is_ip_taken<T>(
+    connected_clients_ipv4: &HashMap<Ipv4Addr, T>,
+    connected_clients_ipv6: &HashMap<Ipv6Addr, T>,
+    tun_ips: IpPair,
+    ips: IpPair,
 ) -> bool {
-    connected_clients.contains_key(&ip.into()) || ip == tun_ip
+    connected_clients_ipv4.contains_key(&ips.ipv4)
+        || connected_clients_ipv6.contains_key(&ips.ipv6)
+        || ips.ipv4 == tun_ips.ipv4
+        || ips.ipv6 == tun_ips.ipv6
 }

 // TODO: brute force approach. We could consider using a more efficient algorithm
-pub(crate) fn find_new_ip(connected_clients: &HashMap<IpAddr, ConnectedClient>) -> Option<IpAddr> {
-    let mut new_ip = generate_random_ip_within_subnet();
+pub(crate) fn find_new_ips<T>(
+    connected_clients_ipv4: &HashMap<Ipv4Addr, T>,
+    connected_clients_ipv6: &HashMap<Ipv6Addr, T>,
+) -> Option<IpPair> {
+    let mut new_ips = generate_random_ips_within_subnet();
    let mut tries = 0;
-    let tun_ip = TUN_DEVICE_ADDRESS.parse::<Ipv4Addr>().unwrap();
-    while is_ip_taken(connected_clients, tun_ip, new_ip) {
-        new_ip = generate_random_ip_within_subnet();
+    let tun_ips = IpPair::new(TUN_DEVICE_ADDRESS_V4, TUN_DEVICE_ADDRESS_V6);
+
+    while is_ip_taken(
+        connected_clients_ipv4,
+        connected_clients_ipv6,
+        tun_ips,
+        new_ips,
+    ) {
+        new_ips = generate_random_ips_within_subnet();
        tries += 1;
        if tries > 100 {
            return None;
        }
    }
-    Some(new_ip.into())
+    Some(new_ips)
 }
@@ -61,7 +61,7 @@ nym-statistics-common = { path = "../../common/statistics" }
 nym-task = { path = "../../common/task" }
 nym-types = { path = "../../common/types" }
 nym-exit-policy = { path = "../../common/exit-policy", features = ["client"] }
-
+nym-id = { path = "../../common/nym-id" }

 [dev-dependencies]
 tempfile = "3.5.0"
@@ -4,14 +4,10 @@
 use crate::cli::try_load_current_config;
 use crate::error::NetworkRequesterError;
 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 nym_id::import_credential;
 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()
@@ -33,8 +29,8 @@ pub(crate) struct Args {
    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,
+    #[clap(long, hide = true)]
+    pub(crate) version: Option<u8>,
 }

 pub(crate) async fn execute(args: Args) -> Result<(), NetworkRequesterError> {
@@ -52,50 +48,7 @@ pub(crate) async fn execute(args: Args) -> Result<(), NetworkRequesterError> {
            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| {
-                NetworkRequesterError::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(NetworkRequesterError::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?;
+    import_credential(credentials_store, raw_credential, args.version).await?;
    Ok(())
 }
@@ -2,11 +2,11 @@
 // SPDX-License-Identifier: GPL-3.0-only

 pub use nym_client_core::error::ClientCoreError;
-use nym_credential_storage::error::StorageError;
+
 use nym_exit_policy::policy::PolicyError;
+use nym_id::NymIdError;
 use nym_socks5_requests::{RemoteAddress, Socks5RequestError};
 use std::net::SocketAddr;
-use time::OffsetDateTime;

 #[derive(thiserror::Error, Debug)]
 pub enum NetworkRequesterError {
@@ -70,21 +70,6 @@ pub enum NetworkRequesterError {
    #[error("can't setup an exit policy without any upstream urls")]
    NoUpstreamExitPolicy,

-    #[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 },
+    #[error(transparent)]
+    NymIdError(#[from] NymIdError),
 }
@@ -0,0 +1,22 @@
+[package]
+name = "nym-id-cli"
+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]
+anyhow.workspace = true
+bs58.workspace = true
+clap = { workspace = true, features = ["derive"] }
+tokio = { workspace = true, features = ["rt-multi-thread", "macros"] }
+tracing.workspace = true
+
+nym-bin-common = { path = "../../common/bin-common", features = ["output_format", "basic_tracing"] }
+nym-credential-storage = { path = "../../common/credential-storage" }
+nym-id = { path = "../../common/nym-id" }
@@ -0,0 +1,15 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_bin_common::bin_info_owned;
+use nym_bin_common::output_format::OutputFormat;
+
+#[derive(clap::Args)]
+pub(crate) struct Args {
+    #[clap(short, long, default_value_t = OutputFormat::default())]
+    output: OutputFormat,
+}
+
+pub(crate) fn execute(args: Args) {
+    println!("{}", args.output.format(&bin_info_owned!()))
+}
@@ -0,0 +1,48 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use clap::ArgGroup;
+use nym_id::import_credential;
+use std::fs;
+use std::path::PathBuf;
+
+fn parse_encoded_credential_data(raw: &str) -> bs58::decode::Result<Vec<u8>> {
+    bs58::decode(raw).into_vec()
+}
+
+#[derive(clap::Args)]
+#[clap(group(ArgGroup::new("cred_data").required(true)))]
+pub(crate) struct Args {
+    /// 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>,
+
+    /// Specifies path to the credentials storage
+    #[clap(long)]
+    pub credentials_store_path: PathBuf,
+
+    // currently hidden as there exists only a single serialization standard
+    #[clap(long, hide = true)]
+    pub(crate) version: Option<u8>,
+}
+
+pub(crate) async fn execute(args: Args) -> anyhow::Result<()> {
+    let credentials_store =
+        nym_credential_storage::initialise_persistent_storage(args.credentials_store_path).await;
+
+    let raw_credential = match args.credential_data {
+        Some(data) => data,
+        None => {
+            // SAFETY: one of those arguments must have been set
+            #[allow(clippy::unwrap_used)]
+            fs::read(args.credential_path.unwrap())?
+        }
+    };
+
+    import_credential(credentials_store, raw_credential, args.version).await?;
+    Ok(())
+}
@@ -0,0 +1,45 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+mod build_info;
+mod import_credential;
+mod setup;
+
+use clap::{Parser, Subcommand};
+use nym_bin_common::bin_info;
+use std::sync::OnceLock;
+
+fn pretty_build_info_static() -> &'static str {
+    static PRETTY_BUILD_INFORMATION: OnceLock<String> = OnceLock::new();
+    PRETTY_BUILD_INFORMATION.get_or_init(|| bin_info!().pretty_print())
+}
+
+#[derive(Parser)]
+#[clap(author = "Nymtech", version, long_version = pretty_build_info_static(), about)]
+pub(crate) struct Cli {
+    #[clap(subcommand)]
+    command: Commands,
+}
+
+impl Cli {
+    pub async fn execute(self) -> anyhow::Result<()> {
+        match self.command {
+            Commands::ImportCredential(args) => import_credential::execute(args).await?,
+            Commands::BuildInfo(args) => build_info::execute(args),
+        }
+
+        Ok(())
+    }
+}
+
+#[derive(Subcommand)]
+pub(crate) enum Commands {
+    // TODO: to be determined how it's going to work in nymvpn et al.
+    // ///
+    // Setup,
+    /// Attempt to import a bandwidth credential into the provided storage.
+    ImportCredential(import_credential::Args),
+
+    /// Show build information of this binary
+    BuildInfo(build_info::Args),
+}
@@ -0,0 +1,2 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
@@ -0,0 +1,19 @@
+// Copyright 2024 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+#![warn(clippy::expect_used)]
+#![warn(clippy::unwrap_used)]
+
+use crate::commands::Cli;
+use clap::Parser;
+use nym_bin_common::logging::setup_tracing_logger;
+
+mod commands;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    setup_tracing_logger();
+    let cli = Cli::parse();
+
+    cli.execute().await
+}
@@ -11174,9 +11174,9 @@ interpret@^2.2.0:
  integrity sha512-Ju0Bz/cEia55xDwUWEa8+olFpCiQoypjnQySseKtmjNrnps3P+xfpUmGr90T7yjlVJmOtybRvPXhKMbHr+fWnw==

 ip@^2.0.0:
-  version "2.0.0"
-  resolved "https://registry.yarnpkg.com/ip/-/ip-2.0.0.tgz#4cf4ab182fee2314c75ede1276f8c80b479936da"
-  integrity sha512-WKa+XuLG1A1R0UWhl2+1XQSi+fZWMsYKffMZTTYsiZaUD8k2yDAj5atimTUD2TZkyCkNEeYE5NhFZmupOGtjYQ==
+  version "2.0.1"
+  resolved "https://registry.yarnpkg.com/ip/-/ip-2.0.1.tgz#e8f3595d33a3ea66490204234b77636965307105"
+  integrity sha512-lJUL9imLTNi1ZfXT+DU6rBBdbiKGBuay9B6xGSPVjUeQwaH1RIGqef8RZkUtHioLmSNpPR5M4HVKJGm1j8FWVQ==

 ipaddr.js@1.9.1:
  version "1.9.1"
Author	SHA1	Message	Date
Bogdan-Ștefan Neacşu	099de36c60	Revert "Remove rustls feature on workspace deps (#4422 )" This reverts commit `2bff66e2c7`.	2024-03-06 12:39:36 +02:00
dependabot[bot]	9e5890a0d7	Bump ip in /clients/native/examples/js-examples/websocket (#4421 ) Bumps [ip](https://github.com/indutny/node-ip) from 1.1.5 to 1.1.9. - [Commits](https://github.com/indutny/node-ip/compare/v1.1.5...v1.1.9) --- updated-dependencies: - dependency-name: ip dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-03-06 08:15:03 +01:00
dependabot[bot]	3bda5f59a3	Bump ip from 2.0.0 to 2.0.1 (#4417 ) Bumps [ip](https://github.com/indutny/node-ip) from 2.0.0 to 2.0.1. - [Commits](https://github.com/indutny/node-ip/compare/v2.0.0...v2.0.1) --- updated-dependencies: - dependency-name: ip dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-03-06 07:58:31 +01:00
import this	154dfa089b	[DOC]: Hotfix - remove unexisting page (#4438 ) * [DOC]: Hotfix - remove unexisting page * update modules and run build * installed with nvm 18 * yarn version solved * remove extra files * attempt to resolve module versioning * Update package versions and fix keplr example --------- Co-authored-by: Mark Sinclair <mmsinclair@users.noreply.github.com>	2024-03-05 15:07:38 +00:00
Jon Häggblad	bd0cbbc18a	Fix typo in macro invocation (#4441 )	2024-03-04 14:48:43 +01:00
Jędrzej Stuczyński	ed0e7a7a25	Merge pull request #4439 from nymtech/chore/move-nym-id Chore/move nym	2024-03-04 12:19:41 +00:00
Jon Häggblad	5b35cfcfb2	build-information: pick up vergen from consuming crate (#4424 )	2024-03-04 12:16:48 +01:00
Bogdan-Ștefan Neacşu	d3ba008b88	Add IPPair constructor (#4440 ) * Add IPPair constructor * Rename	2024-03-04 12:56:10 +02:00
Jędrzej Stuczyński	a04a782dbf	renamed nym-id-lib to nym-id	2024-03-04 10:08:10 +00:00
Jędrzej Stuczyński	f5d9fda0b1	moved and renamed nym-id to nym-id-cli	2024-03-04 09:38:29 +00:00
Bogdan-Ștefan Neacşu	aebd386382	Add IPv6 support to IPPR (#4431 )	2024-03-01 19:28:21 +02:00
Bogdan-Ștefan Neacşu	9a6f96b5e0	Fix windows build (#4426 ) * Fix windows build * Fix in another place too * Install clang * With sudo * Revert "cargo update -p rustls@0.21.7 (#4404)" This reverts commit `ecc47cd418`.	2024-03-01 12:07:38 +02:00
Jędrzej Stuczyński	5a3ff0f9f7	Merge pull request #4436 from nymtech/feature/nym-id-scaffold Feature/nym id scaffold	2024-03-01 09:14:40 +00:00
Jędrzej Stuczyński	160db34651	clippy	2024-02-29 16:53:50 +00:00
Jędrzej Stuczyński	ae20d2afb8	removed old test code	2024-02-29 16:04:07 +00:00
Jędrzej Stuczyński	41b7a2a20d	cargo fmt	2024-02-29 15:57:48 +00:00
Jędrzej Stuczyński	208ec4574b	using the shared code for credentials import	2024-02-29 15:29:41 +00:00
Jon Häggblad	2bff66e2c7	Remove rustls feature on workspace deps (#4422 ) * Remove rustls feature on workspace deps * Cargo.lock for nym-connect and nym-wallet	2024-02-28 18:45:00 +02:00
Jędrzej Stuczyński	1aad5fc1bf	created nym-id for importing credentials	2024-02-28 11:22:46 +00:00
import this	cb3e73fbd7	[DOC]/operators: Validator rewards (#4427 ) * initialise token economics chapter * initialise validator rewards page * add todo points * syntax edits * docs: minor fixes * add currency overview * create bash scripts for nyx stake * add nymvisor url * final version of validator rewards * final version of validator rewards * final version of validator rewards --------- Co-authored-by: Sachin Kamath <github@skamath.me>	2024-02-27 14:17:44 +00:00