feat: add functions to update client configuration and enable masternode sync

Author: QuantumExplorer

dash-spv-ffi/FFI_API.md

@@ -4,7 +4,7 @@ This document provides a comprehensive reference for all FFI (Foreign Function I
 
 **Auto-generated**: This documentation is automatically generated from the source code. Do not edit manually.
 
-**Total Functions**: 61
+**Total Functions**: 63
 
 ## Table of Contents
 
@@ -34,10 +34,11 @@ Functions: 4
 
 ### Configuration
 
-Functions: 23
+Functions: 25
 
 | Function | Description | Module |
 |----------|-------------|--------|
+| `dash_spv_ffi_client_update_config` | Update the running client's configuration | client |
 | `dash_spv_ffi_config_add_peer` | Adds a peer address to the configuration  # Safety - `config` must be a valid... | config |
 | `dash_spv_ffi_config_destroy` | Destroys an FFIClientConfig and frees its memory  # Safety - `config` must be... | config |
 | `dash_spv_ffi_config_get_data_dir` | Gets the data directory path from the configuration  # Safety - `config` must... | config |
@@ -49,6 +50,7 @@ Functions: 23
 | `dash_spv_ffi_config_set_data_dir` | Sets the data directory for storing blockchain data  # Safety - `config` must... | config |
 | `dash_spv_ffi_config_set_fetch_mempool_transactions` | Sets whether to fetch full mempool transaction data  # Safety - `config` must... | config |
 | `dash_spv_ffi_config_set_filter_load` | Sets whether to load bloom filters  # Safety - `config` must be a valid point... | config |
+| `dash_spv_ffi_config_set_masternode_sync_enabled` | Enables or disables masternode synchronization  # Safety - `config` must be a... | config |
 | `dash_spv_ffi_config_set_max_mempool_transactions` | Sets the maximum number of mempool transactions to track  # Safety - `config`... | config |
 | `dash_spv_ffi_config_set_max_peers` | Sets the maximum number of peers to connect to  # Safety - `config` must be a... | config |
 | `dash_spv_ffi_config_set_mempool_strategy` | Sets the mempool synchronization strategy  # Safety - `config` must be a vali... | config |
@@ -198,6 +200,22 @@ dash_spv_ffi_client_stop(client: *mut FFIDashSpvClient) -> i32
 
 ### Configuration - Detailed
 
+#### `dash_spv_ffi_client_update_config`
+
+```c
+dash_spv_ffi_client_update_config(client: *mut FFIDashSpvClient, config: *const FFIClientConfig,) -> i32
+```
+
+**Description:**
+Update the running client's configuration.  # Safety - `client` must be a valid pointer to an `FFIDashSpvClient`. - `config` must be a valid pointer to an `FFIClientConfig`. - The network in `config` must match the client's network; changing networks at runtime is not supported.
+
+**Safety:**
+- `client` must be a valid pointer to an `FFIDashSpvClient`. - `config` must be a valid pointer to an `FFIClientConfig`. - The network in `config` must match the client's network; changing networks at runtime is not supported.
+
+**Module:** `client`
+
+---
+
 #### `dash_spv_ffi_config_add_peer`
 
 ```c
@@ -362,6 +380,22 @@ Sets whether to load bloom filters  # Safety - `config` must be a valid pointer
 
 ---
 
+#### `dash_spv_ffi_config_set_masternode_sync_enabled`
+
+```c
+dash_spv_ffi_config_set_masternode_sync_enabled(config: *mut FFIClientConfig, enable: bool,) -> i32
+```
+
+**Description:**
+Enables or disables masternode 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
+
+**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
+
+**Module:** `config`
+
+---
+
 #### `dash_spv_ffi_config_set_max_mempool_transactions`
 
 ```c

dash-spv-ffi/include/dash_spv_ffi.h

@@ -198,6 +198,17 @@ typedef struct FFIUnconfirmedTransaction {
 
 struct FFIDashSpvClient *dash_spv_ffi_client_new(const FFIClientConfig *config);
 
+/**
+ * Update the running client's configuration.
+ *
+ * # Safety
+ * - `client` must be a valid pointer to an `FFIDashSpvClient`.
+ * - `config` must be a valid pointer to an `FFIClientConfig`.
+ * - The network in `config` must match the client's network; changing networks at runtime is not supported.
+ */
+int32_t dash_spv_ffi_client_update_config(struct FFIDashSpvClient *client,
+                                          const FFIClientConfig *config);
+
 int32_t dash_spv_ffi_client_start(struct FFIDashSpvClient *client);
 
 int32_t dash_spv_ffi_client_stop(struct FFIDashSpvClient *client);
@@ -414,6 +425,16 @@ int32_t dash_spv_ffi_config_set_relay_transactions(FFIClientConfig *config,
 int32_t dash_spv_ffi_config_set_filter_load(FFIClientConfig *config,
                                             bool load_filters);
 
+/**
+ * Enables or disables masternode 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_masternode_sync_enabled(FFIClientConfig *config,
+                                                        bool enable);
+
 /**
  * Gets the network type from the configuration
  *
@@ -541,18 +562,45 @@ int32_t dash_spv_ffi_config_set_start_from_height(FFIClientConfig *config,
 int32_t dash_spv_ffi_config_set_wallet_creation_time(FFIClientConfig *config,
                                                      uint32_t timestamp);
 
+/**
+ * Get the latest checkpoint for the given network.
+ *
+ * # Safety
+ * - `out_height` must be a valid pointer to a `u32`.
+ * - `out_hash` must point to at least 32 writable bytes.
+ */
 int32_t dash_spv_ffi_checkpoint_latest(FFINetwork network, uint32_t *out_height, uint8_t *out_hash);
 
+/**
+ * Get the last checkpoint at or before a given height.
+ *
+ * # Safety
+ * - `out_height` must be a valid pointer to a `u32`.
+ * - `out_hash` must point to at least 32 writable bytes.
+ */
 int32_t dash_spv_ffi_checkpoint_before_height(FFINetwork network,
                                               uint32_t height,
                                               uint32_t *out_height,
                                               uint8_t *out_hash);
 
+/**
+ * Get the last checkpoint at or before a given UNIX timestamp (seconds).
+ *
+ * # Safety
+ * - `out_height` must be a valid pointer to a `u32`.
+ * - `out_hash` must point to at least 32 writable bytes.
+ */
 int32_t dash_spv_ffi_checkpoint_before_timestamp(FFINetwork network,
                                                  uint32_t timestamp,
                                                  uint32_t *out_height,
                                                  uint8_t *out_hash);
 
+/**
+ * Get all checkpoints between two heights (inclusive).
+ *
+ * Returns an `FFIArray` of `FFICheckpoint` items. The caller owns the memory and
+ * must free the array buffer using `dash_spv_ffi_array_destroy` when done.
+ */
 struct FFIArray dash_spv_ffi_checkpoints_between_heights(FFINetwork network,
                                                          uint32_t start_height,
                                                          uint32_t end_height);

dash-spv-ffi/src/client.rs

@@ -339,6 +339,43 @@ impl FFIDashSpvClient {
     }
 }
 
+/// Update the running client's configuration.
+///
+/// # Safety
+/// - `client` must be a valid pointer to an `FFIDashSpvClient`.
+/// - `config` must be a valid pointer to an `FFIClientConfig`.
+/// - The network in `config` must match the client's network; changing networks at runtime is not supported.
+#[no_mangle]
+pub unsafe extern "C" fn dash_spv_ffi_client_update_config(
+    client: *mut FFIDashSpvClient,
+    config: *const FFIClientConfig,
+) -> i32 {
+    null_check!(client);
+    null_check!(config);
+
+    let client = &(*client);
+    let new_config = (&*config).clone_inner();
+
+    let result = client.runtime.block_on(async {
+        let mut guard = client.inner.lock().unwrap();
+        if let Some(ref mut spv_client) = *guard {
+            spv_client.update_config(new_config).await.map_err(|e| e)
+        } else {
+            Err(dash_spv::SpvError::Config(
+                "Client not initialized".to_string(),
+            ))
+        }
+    });
+
+    match result {
+        Ok(()) => FFIErrorCode::Success as i32,
+        Err(e) => {
+            set_last_error(&e.to_string());
+            FFIErrorCode::from(e) as i32
+        }
+    }
+}
+
 #[no_mangle]
 pub unsafe extern "C" fn dash_spv_ffi_client_start(client: *mut FFIDashSpvClient) -> i32 {
     null_check!(client);

dash-spv-ffi/src/config.rs

@@ -208,6 +208,23 @@ pub unsafe extern "C" fn dash_spv_ffi_config_set_filter_load(
     FFIErrorCode::Success as i32
 }
 
+/// Enables or disables masternode 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
+#[no_mangle]
+pub unsafe extern "C" fn dash_spv_ffi_config_set_masternode_sync_enabled(
+    config: *mut FFIClientConfig,
+    enable: bool,
+) -> i32 {
+    null_check!(config);
+
+    let config = &mut (*config).inner;
+    config.enable_masternodes = enable;
+    FFIErrorCode::Success as i32
+}
+
 /// Gets the network type from the configuration
 ///
 /// # Safety

dash-spv/src/client/mod.rs

@@ -611,6 +611,38 @@ impl<
         Ok(())
     }
 
+    /// Update the client's configuration at runtime.
+    ///
+    /// This applies non-network-critical settings without restarting the client.
+    /// Changing the network is not supported at runtime.
+    pub async fn update_config(&mut self, new_config: ClientConfig) -> Result<()> {
+        if new_config.network != self.config.network {
+            return Err(SpvError::Config(
+                "Cannot change network at runtime".to_string(),
+            ));
+        }
+
+        // Track changes that may require reinitialization of helpers
+        let mempool_changed =
+            new_config.enable_mempool_tracking != self.config.enable_mempool_tracking
+                || new_config.mempool_strategy != self.config.mempool_strategy
+                || new_config.max_mempool_transactions != self.config.max_mempool_transactions
+                || new_config.recent_send_window_secs != self.config.recent_send_window_secs;
+
+        // Apply full config replacement, preserving network (already checked equal)
+        self.config = new_config;
+
+        // Update validation manager according to new mode
+        self.validation = ValidationManager::new(self.config.validation_mode);
+
+        // Rebuild mempool filter if needed
+        if mempool_changed {
+            self.update_mempool_filter().await;
+        }
+
+        Ok(())
+    }
+
     /// Synchronize to the tip of the blockchain.
     pub async fn sync_to_tip(&mut self) -> Result<SyncProgress> {
         let running = self.running.read().await;