more work

Author: QuantumExplorer

dash-spv-ffi/FFI_API.md

@@ -14,7 +14,6 @@ exclude = ["Option_BlockCallback", "Option_TransactionCallback", "Option_Balance
 prefix = "dash_spv_ffi_"
 
 [export.rename]
-"FFINetwork" = "DashSpvNetwork"
 "FFIValidationMode" = "DashSpvValidationMode"
 "FFIErrorCode" = "DashSpvErrorCode"
 

dash-spv-ffi/cbindgen.toml

@@ -1,16 +1,11 @@
 /// Example demonstrating the simplified FFIWalletManager usage
-/// 
+///
 /// The refactored design removes unnecessary indirection by:
 /// 1. FFIWalletManager directly contains Arc<RwLock<WalletManager>>
 /// 2. No longer requires going through the client for each operation
 /// 3. Cleaner and more efficient access to wallet functionality
-
 use dash_spv_ffi::*;
-use key_wallet_ffi::{
-    wallet_manager_wallet_count,
-    wallet_manager_free,
-    FFIError,
-};
+use key_wallet_ffi::{wallet_manager_free, wallet_manager_wallet_count, FFIError};
 
 fn main() {
     unsafe {
@@ -19,13 +14,13 @@ fn main() {
         if config.is_null() {
             panic!("Failed to create config");
         }
-        
+
         // Create an SPV client
         let client = dash_spv_ffi_client_new(config);
         if client.is_null() {
             panic!("Failed to create client");
         }
-        
+
         // Get the wallet manager - now returns void* for Swift compatibility
         // This contains a cloned Arc to the wallet manager, allowing
         // direct interaction without going through the client
@@ -35,19 +30,19 @@ fn main() {
         }
         // Cast back to FFIWalletManager for use
         let wallet_manager = wallet_manager_ptr as *mut key_wallet_ffi::FFIWalletManager;
-        
+
         // Now we can use the wallet manager directly
         // No need to go through client -> inner -> spv_client -> wallet()
-        
+
         // Get the number of wallets (should be 0 initially)
         let mut error = std::mem::zeroed::<FFIError>();
         let wallet_count = wallet_manager_wallet_count(wallet_manager, &mut error);
         println!("Number of wallets: {}", wallet_count);
-        
+
         // Note: To get total balance, you would need to iterate through wallets
         // For now, just show the wallet count
         println!("Currently managing {} wallets", wallet_count);
-        
+
         // Example of processing a transaction (with mock data)
         // In real usage, you would have actual transaction hex
         /*
@@ -60,21 +55,21 @@ fn main() {
             100000, // block height
             &mut error
         );
-        
+
         if affected >= 0 {
             println!("Transaction affected {} wallets", affected);
         } else {
             println!("Failed to process transaction");
         }
         */
-        
+
         // Clean up
         // The wallet manager can now be independently destroyed
         // It maintains its own Arc reference to the underlying wallet
         wallet_manager_free(wallet_manager);
         dash_spv_ffi_client_destroy(client);
         dash_spv_ffi_config_destroy(config);
-        
+
         println!("Example completed successfully!");
     }
-}
+}

dash-spv-ffi/examples/wallet_manager_usage.rs

@@ -9,13 +9,6 @@ typedef enum FFIMempoolStrategy {
   Selective = 2,
 } FFIMempoolStrategy;
 
-typedef enum FFINetwork {
-  Dash = 0,
-  Testnet = 1,
-  Regtest = 2,
-  Devnet = 3,
-} FFINetwork;
-
 typedef enum FFISyncStage {
   Connecting = 0,
   QueryingHeight = 1,
@@ -342,54 +335,211 @@ int32_t dash_spv_ffi_client_record_send(struct FFIDashSpvClient *client, const c
  */
 void *dash_spv_ffi_client_get_wallet_manager(struct FFIDashSpvClient *client);
 
-FFIClientConfig *dash_spv_ffi_config_new(enum FFINetwork network);
+FFIClientConfig *dash_spv_ffi_config_new(FFINetwork network);
 
 FFIClientConfig *dash_spv_ffi_config_mainnet(void);
 
 FFIClientConfig *dash_spv_ffi_config_testnet(void);
 
-int32_t dash_spv_ffi_config_set_data_dir(FFIClientConfig *config, const char *path);
+/**
+ * Sets the data directory for storing blockchain data
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - `path` must be a valid null-terminated C string
+ * - The caller must ensure the config pointer remains valid for the duration of this call
+ */
+int32_t dash_spv_ffi_config_set_data_dir(FFIClientConfig *config,
+                                         const char *path);
 
+/**
+ * Sets the validation mode for the SPV client
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - The caller must ensure the config pointer remains valid for the duration of this call
+ */
 int32_t dash_spv_ffi_config_set_validation_mode(FFIClientConfig *config,
                                                 enum FFIValidationMode mode);
 
-int32_t dash_spv_ffi_config_set_max_peers(FFIClientConfig *config, uint32_t max_peers);
+/**
+ * Sets the maximum number of peers to connect to
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - The caller must ensure the config pointer remains valid for the duration of this call
+ */
+int32_t dash_spv_ffi_config_set_max_peers(FFIClientConfig *config,
+                                          uint32_t max_peers);
 
-int32_t dash_spv_ffi_config_add_peer(FFIClientConfig *config, const char *addr);
+/**
+ * Adds a peer address to the configuration
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - `addr` must be a valid null-terminated C string containing a socket address (e.g., "192.168.1.1:9999")
+ * - The caller must ensure both pointers remain valid for the duration of this call
+ */
+int32_t dash_spv_ffi_config_add_peer(FFIClientConfig *config,
+                                     const char *addr);
 
-int32_t dash_spv_ffi_config_set_user_agent(FFIClientConfig *config, const char *user_agent);
+/**
+ * Sets the user agent string (currently not supported)
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - `user_agent` must be a valid null-terminated C string
+ * - The caller must ensure both pointers remain valid for the duration of this call
+ */
+int32_t dash_spv_ffi_config_set_user_agent(FFIClientConfig *config,
+                                           const char *user_agent);
 
-int32_t dash_spv_ffi_config_set_relay_transactions(FFIClientConfig *config, bool _relay);
+/**
+ * Sets whether to relay transactions (currently a no-op)
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - The caller must ensure the config pointer remains valid for the duration of this call
+ */
+int32_t dash_spv_ffi_config_set_relay_transactions(FFIClientConfig *config,
+                                                   bool _relay);
 
-int32_t dash_spv_ffi_config_set_filter_load(FFIClientConfig *config, bool load_filters);
+/**
+ * Sets whether to load bloom filters
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - The caller must ensure the config pointer remains valid for the duration of this call
+ */
+int32_t dash_spv_ffi_config_set_filter_load(FFIClientConfig *config,
+                                            bool load_filters);
 
-enum FFINetwork dash_spv_ffi_config_get_network(const FFIClientConfig *config);
+/**
+ * Gets the network type from the configuration
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig or null
+ * - If null, returns FFINetwork::Dash as default
+ */
+FFINetwork dash_spv_ffi_config_get_network(const FFIClientConfig *config);
 
+/**
+ * Gets the data directory path from the configuration
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig or null
+ * - If null or no data directory is set, returns an FFIString with null pointer
+ * - The returned FFIString must be freed by the caller using dash_string_free
+ */
 struct FFIString dash_spv_ffi_config_get_data_dir(const FFIClientConfig *config);
 
+/**
+ * Destroys an FFIClientConfig and frees its memory
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet, or null
+ * - After calling this function, the config pointer becomes invalid and must not be used
+ * - This function should only be called once per config instance
+ */
 void dash_spv_ffi_config_destroy(FFIClientConfig *config);
 
-int32_t dash_spv_ffi_config_set_mempool_tracking(FFIClientConfig *config, bool enable);
+/**
+ * Enables or disables mempool tracking
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - The caller must ensure the config pointer remains valid for the duration of this call
+ */
+int32_t dash_spv_ffi_config_set_mempool_tracking(FFIClientConfig *config,
+                                                 bool enable);
 
+/**
+ * Sets the mempool synchronization strategy
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - The caller must ensure the config pointer remains valid for the duration of this call
+ */
 int32_t dash_spv_ffi_config_set_mempool_strategy(FFIClientConfig *config,
                                                  enum FFIMempoolStrategy strategy);
 
+/**
+ * Sets the maximum number of mempool transactions to track
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - The caller must ensure the config pointer remains valid for the duration of this call
+ */
 int32_t dash_spv_ffi_config_set_max_mempool_transactions(FFIClientConfig *config,
                                                          uint32_t max_transactions);
 
-int32_t dash_spv_ffi_config_set_mempool_timeout(FFIClientConfig *config, uint64_t timeout_secs);
+/**
+ * Sets the mempool transaction timeout in seconds
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - The caller must ensure the config pointer remains valid for the duration of this call
+ */
+int32_t dash_spv_ffi_config_set_mempool_timeout(FFIClientConfig *config,
+                                                uint64_t timeout_secs);
 
-int32_t dash_spv_ffi_config_set_fetch_mempool_transactions(FFIClientConfig *config, bool fetch);
+/**
+ * Sets whether to fetch full mempool transaction data
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - The caller must ensure the config pointer remains valid for the duration of this call
+ */
+int32_t dash_spv_ffi_config_set_fetch_mempool_transactions(FFIClientConfig *config,
+                                                           bool fetch);
 
-int32_t dash_spv_ffi_config_set_persist_mempool(FFIClientConfig *config, bool persist);
+/**
+ * Sets whether to persist mempool state to disk
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - The caller must ensure the config pointer remains valid for the duration of this call
+ */
+int32_t dash_spv_ffi_config_set_persist_mempool(FFIClientConfig *config,
+                                                bool persist);
 
+/**
+ * Gets whether mempool tracking is enabled
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig or null
+ * - If null, returns false as default
+ */
 bool dash_spv_ffi_config_get_mempool_tracking(const FFIClientConfig *config);
 
+/**
+ * Gets the mempool synchronization strategy
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig or null
+ * - If null, returns FFIMempoolStrategy::Selective as default
+ */
 enum FFIMempoolStrategy dash_spv_ffi_config_get_mempool_strategy(const FFIClientConfig *config);
 
-int32_t dash_spv_ffi_config_set_start_from_height(FFIClientConfig *config, uint32_t height);
+/**
+ * Sets the starting block height for synchronization
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - The caller must ensure the config pointer remains valid for the duration of this call
+ */
+int32_t dash_spv_ffi_config_set_start_from_height(FFIClientConfig *config,
+                                                  uint32_t height);
 
-int32_t dash_spv_ffi_config_set_wallet_creation_time(FFIClientConfig *config, uint32_t timestamp);
+/**
+ * Sets the wallet creation timestamp for synchronization optimization
+ *
+ * # Safety
+ * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet
+ * - The caller must ensure the config pointer remains valid for the duration of this call
+ */
+int32_t dash_spv_ffi_config_set_wallet_creation_time(FFIClientConfig *config,
+                                                     uint32_t timestamp);
 
 const char *dash_spv_ffi_get_last_error(void);
 
@@ -503,8 +653,6 @@ int32_t dash_spv_ffi_init_logging(const char *level);
 
 const char *dash_spv_ffi_version(void);
 
-const char *dash_spv_ffi_get_network_name(enum FFINetwork network);
-
 void dash_spv_ffi_enable_test_mode(void);
 
 int32_t dash_spv_ffi_client_broadcast_transaction(struct FFIDashSpvClient *client,

dash-spv-ffi/include/dash_spv_ffi.h

@@ -1,6 +1,6 @@
+use crate::{null_check, set_last_error, FFIDashSpvClient, FFIErrorCode};
 use std::ffi::CStr;
 use std::os::raw::c_char;
-use crate::{null_check, set_last_error, FFIDashSpvClient, FFIErrorCode};
 
 #[no_mangle]
 pub unsafe extern "C" fn dash_spv_ffi_client_broadcast_transaction(
@@ -56,4 +56,4 @@ pub unsafe extern "C" fn dash_spv_ffi_client_broadcast_transaction(
             FFIErrorCode::from(e) as i32
         }
     }
-}
+}