feat: add derive_store_id function

Author: ovitrif

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "vss-rust-client-ffi"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 

Cargo.toml

@@ -32,12 +32,19 @@ cargo build --release
 ```swift
 import vss_rust_client_ffi
 
-// Initialize VSS client with LNURL-auth
+let mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
+let passphrase: String? = nil
+let storeId = try vssDeriveStoreId(
+    prefix: "bitkit_v1_regtest",
+    mnemonic: mnemonic,
+    passphrase: passphrase
+)
+
 try await vssNewClientWithLnurlAuth(
     baseUrl: "https://vss.example.com",
-    storeId: "my-app-store",
-    mnemonic: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
-    passphrase: nil,
+    storeId: storeId,
+    mnemonic: mnemonic,
+    passphrase: passphrase,
     lnurlAuthServerUrl: "https://auth.example.com/lnurl"
 )
 
@@ -73,12 +80,19 @@ vssShutdownClient()
 ```python
 from vss_rust_client_ffi import *
 
-# Initialize VSS client with LNURL-auth
+mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
+passphrase = None
+store_id = vss_derive_store_id(
+    prefix="bitkit_v1_regtest",
+    mnemonic=mnemonic,
+    passphrase=passphrase
+)
+
 await vss_new_client_with_lnurl_auth(
     "https://vss.example.com",
-    "my-app-store",
-    "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
-    None,  # passphrase
+    store_id,
+    mnemonic,
+    passphrase,
     "https://auth.example.com/lnurl"
 )
 
@@ -117,12 +131,19 @@ vss_shutdown_client()
 ```kotlin
 import uniffi.vss_rust_client_ffi.*
 
-// Initialize VSS client with LNURL-auth
+val mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
+val passphrase: String? = null
+val storeId = vssDeriveStoreId(
+    prefix = "bitkit_v1_regtest",
+    mnemonic = mnemonic,
+    passphrase = passphrase
+)
+
 vssNewClientWithLnurlAuth(
     baseUrl = "https://vss.example.com",
-    storeId = "my-app-store",
-    mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
-    passphrase = null,
+    storeId = storeId,
+    mnemonic = mnemonic,
+    passphrase = passphrase,
     lnurlAuthServerUrl = "https://auth.example.com/lnurl"
 )
 
@@ -171,6 +192,15 @@ Initialize the global VSS client connection with LNURL-auth authentication. Prov
 #### `vssShutdownClient() -> Void`
 Shutdown the VSS client and clean up resources. Optional but recommended for clean application shutdown.
 
+### Utility Functions
+
+#### `vssDeriveStoreId(prefix: String, mnemonic: String, passphrase: String?) -> String`
+Derives a deterministic VSS store ID from a mnemonic and optional passphrase using BIP32 key derivation.
+
+- `prefix`: A prefix to include in the store ID (e.g., "bitkit_v1_regtest")
+- `mnemonic`: BIP39 mnemonic phrase (12 or 24 words)  
+- `passphrase`: Optional BIP39 passphrase
+
 ### Data Operations
 
 #### `vssStore(key: String, value: Data) -> VssItem`
@@ -294,4 +324,4 @@ This project is licensed under the MIT License - see the LICENSE file for detail
 
 - [VSS Server](https://github.com/lightningdevkit/vss-server) - The VSS server implementation
 - [vss-client](https://crates.io/crates/vss-client) - The underlying Rust client library
-- [UniFFI](https://mozilla.github.io/uniffi-rs/) - The FFI binding generator
+- [UniFFI](https://mozilla.github.io/uniffi-rs/) - The FFI binding generator

README.md

@@ -3,4 +3,4 @@ android.useAndroidX=true
 android.nonTransitiveRClass=true
 kotlin.code.style=official
 # project settings:
-version=0.2.0
+version=0.3.0

bindings/android/gradle.properties

@@ -21,9 +21,70 @@ use vss_client::util::retry::{
     MaxAttemptsRetryPolicy, MaxTotalDelayRetryPolicy, RetryPolicy,
 };
 use vss_client::util::storable_builder::{EntropySource, StorableBuilder};
+use bip39::Mnemonic;
+use std::str::FromStr;
 
 const VSS_HARDENED_CHILD_INDEX: u32 = 877;
 const VSS_LNURL_AUTH_HARDENED_CHILD_INDEX: u32 = 138;
+const VSS_STORE_ID_HARDENED_CHILD_INDEX: u32 = 118;
+const VSS_STORE_ID_HASH_LENGTH: usize = 36;
+
+/// Derives a deterministic VSS store ID from a mnemonic and optional passphrase.
+///
+/// # Parameters
+/// - `prefix`: A prefix to include in the store ID
+/// - `mnemonic`: BIP39 mnemonic phrase (12 or 24 words)
+/// - `passphrase`: Optional BIP39 passphrase
+///
+/// # Returns
+/// A store ID string or VssError on failure
+pub fn derive_vss_store_id(
+    prefix: String,
+    mnemonic: String,
+    passphrase: Option<String>,
+) -> Result<String, VssError> {
+    let mnemonic = Mnemonic::from_str(&mnemonic).map_err(|e| VssError::ConnectionError {
+        error_details: format!("Invalid mnemonic: {}", e),
+    })?;
+
+    let seed = match passphrase {
+        Some(passphrase) => mnemonic.to_seed(&passphrase),
+        None => mnemonic.to_seed(""),
+    };
+    let seed_array: [u8; 32] = seed[..32]
+        .try_into()
+        .map_err(|_| VssError::ConnectionError {
+            error_details: "Failed to extract seed from mnemonic".to_string(),
+        })?;
+
+    let secp = Secp256k1::new();
+    let master_xprv = Xpriv::new_master(Network::Bitcoin, &seed_array).map_err(|e| {
+        VssError::ConnectionError {
+            error_details: format!("Failed to create master key: {}", e),
+        }
+    })?;
+
+    let vss_store_id_xprv = master_xprv
+        .derive_priv(
+            &secp,
+            &[
+                ChildNumber::Hardened { index: VSS_HARDENED_CHILD_INDEX },
+                ChildNumber::Hardened { index: VSS_STORE_ID_HARDENED_CHILD_INDEX },
+            ],
+        )
+        .map_err(|e| VssError::ConnectionError {
+            error_details: format!("Failed to derive VSS store ID key: {}", e),
+        })?;
+
+    let store_id_key = vss_store_id_xprv.private_key.secret_bytes();
+    let hash = sha256::Hash::hash(&store_id_key);
+    let hash_hex = hash.to_string();
+
+    let store_id_suffix = &hash_hex[..VSS_STORE_ID_HASH_LENGTH];
+    let store_id = format!("{}_{}", prefix, store_id_suffix);
+
+    Ok(store_id)
+}
 
 type CustomRetryPolicy = FilteredRetryPolicy<
     JitteredRetryPolicy<

src/implementation.rs

@@ -6,7 +6,7 @@ mod tests;
 mod types;
 
 pub use errors::*;
-pub use implementation::VssClient;
+pub use implementation::{VssClient, derive_vss_store_id};
 pub use types::*;
 
 uniffi::setup_scaffolding!();
@@ -338,6 +338,38 @@ pub async fn vss_delete(
     })
 }
 
+/// Derives a deterministic VSS store ID from a mnemonic and optional passphrase.
+///
+/// This function creates a consistent store ID that can be used across devices for the same wallet.
+/// The store ID is derived using BIP32 key derivation at a specific VSS path, ensuring it's
+/// cryptographically secure and deterministic.
+///
+/// # Parameters
+/// - `prefix`: A prefix to include in the store ID (e.g., "bitkit_v1_regtest")
+/// - `mnemonic`: BIP39 mnemonic phrase (12 or 24 words)
+/// - `passphrase`: Optional BIP39 passphrase
+///
+/// # Returns
+/// A deterministic store ID string that combines the prefix with a derived identifier.
+///
+/// # Example
+/// ```
+/// let store_id = vss_derive_store_id(
+///     "bitkit_v1_regtest".to_string(),
+///     "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about".to_string(),
+///     None
+/// )?;
+/// println!("Store ID: {}", store_id);
+/// ```
+#[uniffi::export]
+pub fn vss_derive_store_id(
+    prefix: String,
+    mnemonic: String,
+    passphrase: Option<String>,
+) -> Result<String, VssError> {
+    derive_vss_store_id(prefix, mnemonic, passphrase)
+}
+
 /// Shuts down the VSS client and clears the global client state.
 ///
 /// This function is optional but recommended for clean shutdown in applications

src/lib.rs

@@ -77,6 +77,27 @@ mod tests {
         assert!(format!("{}", get_err).contains("Test get error"));
     }
 
+    #[test]
+    fn test_vss_derive_store_id() {
+        use crate::vss_derive_store_id;
+
+        let prefix = "test".to_string();
+        let mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about".to_string();
+
+        // Test deterministic output
+        let store_id1 = vss_derive_store_id(prefix.clone(), mnemonic.clone(), None).unwrap();
+        let store_id2 = vss_derive_store_id(prefix.clone(), mnemonic.clone(), None).unwrap();
+        assert_eq!(store_id1, store_id2);
+        assert!(store_id1.starts_with("test_"));
+
+        // Test passphrase handling
+        let with_passphrase = vss_derive_store_id(prefix.clone(), mnemonic.clone(), Some("pass".to_string())).unwrap();
+        assert_ne!(store_id1, with_passphrase);
+
+        // Test invalid mnemonic
+        assert!(vss_derive_store_id(prefix, "invalid".to_string(), None).is_err());
+    }
+
     #[test]
     fn test_types_creation() {
         use crate::{VssItem, KeyValue, KeyVersion};