feat: report/propagate client start/run failures

We currently just silently ignore any failure inside the sync coordinator or `monitor_network` thread. This PR propagates them and also adds a FFI callback structure which can be set to receive notifications about errors inside the SPV client.

Author: xdustinface

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**: 54
+**Total Functions**: 56
 
 ## Table of Contents
 
@@ -87,12 +87,14 @@ Functions: 2
 
 ### Event Callbacks
 
-Functions: 4
+Functions: 6
 
 | Function | Description | Module |
 |----------|-------------|--------|
+| `dash_spv_ffi_client_clear_client_error_callback` | Clear the client error callback | client |
 | `dash_spv_ffi_client_clear_network_event_callbacks` | Clear network event callbacks | client |
 | `dash_spv_ffi_client_clear_progress_callback` | Clear progress callback | client |
+| `dash_spv_ffi_client_set_client_error_callback` | Set a callback for fatal client errors (start failure, sync thread crash) | client |
 | `dash_spv_ffi_client_set_network_event_callbacks` | Set network event callbacks for push-based event notifications | client |
 | `dash_spv_ffi_client_set_progress_callback` | Set progress callback for sync progress updates | client |
 
@@ -621,6 +623,22 @@ This function is unsafe because: - The caller must ensure all pointers are valid
 
 ### Event Callbacks - Detailed
 
+#### `dash_spv_ffi_client_clear_client_error_callback`
+
+```c
+dash_spv_ffi_client_clear_client_error_callback(client: *mut FFIDashSpvClient,) -> i32
+```
+
+**Description:**
+Clear the client error callback.  # Safety - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`.
+
+**Safety:**
+- `client` must be a valid, non-null pointer to an `FFIDashSpvClient`.
+
+**Module:** `client`
+
+---
+
 #### `dash_spv_ffi_client_clear_network_event_callbacks`
 
 ```c
@@ -653,6 +671,22 @@ Clear progress callback.  # Safety - `client` must be a valid, non-null pointer
 
 ---
 
+#### `dash_spv_ffi_client_set_client_error_callback`
+
+```c
+dash_spv_ffi_client_set_client_error_callback(client: *mut FFIDashSpvClient, callback: FFIClientErrorCallback,) -> i32
+```
+
+**Description:**
+Set a callback for fatal client errors (start failure, sync thread crash).  # Safety - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - The `callback` struct and its `user_data` must remain valid until the callback is cleared. - The callback must be thread-safe as it may be called from a background thread.
+
+**Safety:**
+- `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - The `callback` struct and its `user_data` must remain valid until the callback is cleared. - The callback must be thread-safe as it may be called from a background thread.
+
+**Module:** `client`
+
+---
+
 #### `dash_spv_ffi_client_set_network_event_callbacks`
 
 ```c

dash-spv-ffi/include/dash_spv_ffi.h

@@ -433,6 +433,23 @@ typedef struct FFIProgressCallback {
   void *user_data;
 } FFIProgressCallback;
 
+/**
+ * Callback for fatal client errors (e.g. start failure, monitor thread crash).
+ *
+ * The `error` string pointer is borrowed and only valid for the duration
+ * of the callback. Callers must copy the string if they need to retain it
+ * after the callback returns.
+ */
+typedef void (*OnClientErrorCallback)(const char *error, void *user_data);
+
+/**
+ * Client error callback configuration.
+ */
+typedef struct FFIClientErrorCallback {
+  OnClientErrorCallback on_error;
+  void *user_data;
+} FFIClientErrorCallback;
+
 /**
  * FFIResult type for error handling
  */
@@ -752,6 +769,27 @@ int32_t dash_spv_ffi_client_set_progress_callback(struct FFIDashSpvClient *clien
  */
  int32_t dash_spv_ffi_client_clear_progress_callback(struct FFIDashSpvClient *client) ;
 
+/**
+ * Set a callback for fatal client errors (start failure, sync thread crash).
+ *
+ * # Safety
+ * - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`.
+ * - The `callback` struct and its `user_data` must remain valid until the callback is cleared.
+ * - The callback must be thread-safe as it may be called from a background thread.
+ */
+
+int32_t dash_spv_ffi_client_set_client_error_callback(struct FFIDashSpvClient *client,
+                                                      struct FFIClientErrorCallback callback)
+;
+
+/**
+ * Clear the client error callback.
+ *
+ * # Safety
+ * - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`.
+ */
+ int32_t dash_spv_ffi_client_clear_client_error_callback(struct FFIDashSpvClient *client) ;
+
  struct FFIClientConfig *dash_spv_ffi_config_new(FFINetwork network) ;
 
  struct FFIClientConfig *dash_spv_ffi_config_mainnet(void) ;

dash-spv-ffi/src/callbacks.rs

@@ -569,6 +569,47 @@ impl Default for FFIWalletEventCallbacks {
     }
 }
 
+// ============================================================================
+// FFIClientErrorCallback - Fatal client-level errors
+// ============================================================================
+
+/// Callback for fatal client errors (e.g. start failure, monitor thread crash).
+///
+/// The `error` string pointer is borrowed and only valid for the duration
+/// of the callback. Callers must copy the string if they need to retain it
+/// after the callback returns.
+pub type OnClientErrorCallback =
+    Option<extern "C" fn(error: *const c_char, user_data: *mut c_void)>;
+
+/// Client error callback configuration.
+#[repr(C)]
+pub struct FFIClientErrorCallback {
+    pub on_error: OnClientErrorCallback,
+    pub user_data: *mut c_void,
+}
+
+unsafe impl Send for FFIClientErrorCallback {}
+unsafe impl Sync for FFIClientErrorCallback {}
+
+impl Default for FFIClientErrorCallback {
+    fn default() -> Self {
+        Self {
+            on_error: None,
+            user_data: std::ptr::null_mut(),
+        }
+    }
+}
+
+impl FFIClientErrorCallback {
+    /// Dispatch a client error to the callback.
+    pub fn dispatch(&self, error: &str) {
+        if let Some(cb) = self.on_error {
+            let c_error = CString::new(error).unwrap_or_default();
+            cb(c_error.as_ptr(), self.user_data);
+        }
+    }
+}
+
 impl FFIWalletEventCallbacks {
     /// Dispatch a WalletEvent to the appropriate callback.
     pub fn dispatch(&self, event: &key_wallet_manager::WalletEvent) {

dash-spv-ffi/src/client.rs

@@ -1,7 +1,7 @@
 use crate::{
-    null_check, set_last_error, FFIClientConfig, FFIErrorCode, FFINetworkEventCallbacks,
-    FFIProgressCallback, FFISyncEventCallbacks, FFISyncProgress, FFIWalletEventCallbacks,
-    FFIWalletManager,
+    null_check, set_last_error, FFIClientConfig, FFIClientErrorCallback, FFIErrorCode,
+    FFINetworkEventCallbacks, FFIProgressCallback, FFISyncEventCallbacks, FFISyncProgress,
+    FFIWalletEventCallbacks, FFIWalletManager,
 };
 // Import wallet types from key-wallet-ffi
 use key_wallet_ffi::FFIWalletManager as KeyWalletFFIWalletManager;
@@ -130,6 +130,7 @@ pub struct FFIDashSpvClient {
     network_event_callbacks: Arc<Mutex<Option<FFINetworkEventCallbacks>>>,
     wallet_event_callbacks: Arc<Mutex<Option<FFIWalletEventCallbacks>>>,
     progress_callback: Arc<Mutex<Option<FFIProgressCallback>>>,
+    client_error_callback: Arc<Mutex<Option<FFIClientErrorCallback>>>,
 }
 
 /// Create a new SPV client and return an opaque pointer.
@@ -189,6 +190,7 @@ pub unsafe extern "C" fn dash_spv_ffi_client_new(
                 network_event_callbacks: Arc::new(Mutex::new(None)),
                 wallet_event_callbacks: Arc::new(Mutex::new(None)),
                 progress_callback: Arc::new(Mutex::new(None)),
+                client_error_callback: Arc::new(Mutex::new(None)),
             };
             Box::into_raw(Box::new(ffi_client))
         }
@@ -380,34 +382,6 @@ pub unsafe extern "C" fn dash_spv_ffi_client_run(client: *mut FFIDashSpvClient)
 
     tracing::info!("dash_spv_ffi_client_run: starting client");
 
-    // Start the client first
-    let inner = client.inner.clone();
-    let start_result = client.runtime.block_on(async {
-        let mut spv_client = {
-            let mut guard = inner.lock().unwrap();
-            match guard.take() {
-                Some(c) => c,
-                None => {
-                    return Err(dash_spv::SpvError::Storage(dash_spv::StorageError::NotFound(
-                        "Client not initialized".to_string(),
-                    )))
-                }
-            }
-        };
-        let res = spv_client.start().await;
-        let mut guard = inner.lock().unwrap();
-        *guard = Some(spv_client);
-        res
-    });
-
-    if let Err(e) = start_result {
-        tracing::error!("dash_spv_ffi_client_run: start failed: {}", e);
-        set_last_error(&e.to_string());
-        return FFIErrorCode::from(e) as i32;
-    }
-
-    tracing::info!("dash_spv_ffi_client_run: client started, setting up event monitoring");
-
     // Get event subscriptions before taking the client for the sync thread.
     // The sync thread needs exclusive access, so we must subscribe first.
     let inner = client.inner.clone();
@@ -487,6 +461,8 @@ pub unsafe extern "C" fn dash_spv_ffi_client_run(client: *mut FFIDashSpvClient)
 
     tracing::info!("dash_spv_ffi_client_run: spawning sync thread");
 
+    let error_callback = client.client_error_callback.clone();
+
     // Now take the client for the sync thread
     let spv_client = {
         let mut guard = inner.lock().unwrap();
@@ -506,7 +482,19 @@ pub unsafe extern "C" fn dash_spv_ffi_client_run(client: *mut FFIDashSpvClient)
 
             let mut spv_client = spv_client;
 
-            tracing::debug!("Sync thread: got client, starting monitor_network");
+            if let Err(e) = spv_client.start().await {
+                tracing::error!("Sync thread: client start error: {}", e);
+                let guard = error_callback.lock().unwrap();
+                if let Some(cb) = guard.as_ref() {
+                    cb.dispatch(&e.to_string());
+                }
+                drop(guard);
+                let mut guard = inner.lock().unwrap();
+                *guard = Some(spv_client);
+                return;
+            }
+
+            tracing::debug!("Sync thread: starting monitor_network");
 
             let (_command_sender, command_receiver) = tokio::sync::mpsc::unbounded_channel();
             let run_token = shutdown_token.clone();
@@ -536,6 +524,11 @@ pub unsafe extern "C" fn dash_spv_ffi_client_run(client: *mut FFIDashSpvClient)
 
             if let Err(e) = result {
                 tracing::error!("Sync thread: sync error: {}", e);
+                let guard = error_callback.lock().unwrap();
+                if let Some(cb) = guard.as_ref() {
+                    cb.dispatch(&e.to_string());
+                }
+                drop(guard);
             }
 
             tracing::debug!("Sync thread: putting client back");
@@ -1071,3 +1064,38 @@ pub unsafe extern "C" fn dash_spv_ffi_client_clear_progress_callback(
 
     FFIErrorCode::Success as i32
 }
+
+/// Set a callback for fatal client errors (start failure, sync thread crash).
+///
+/// # Safety
+/// - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`.
+/// - The `callback` struct and its `user_data` must remain valid until the callback is cleared.
+/// - The callback must be thread-safe as it may be called from a background thread.
+#[no_mangle]
+pub unsafe extern "C" fn dash_spv_ffi_client_set_client_error_callback(
+    client: *mut FFIDashSpvClient,
+    callback: FFIClientErrorCallback,
+) -> i32 {
+    null_check!(client);
+
+    let client = &(*client);
+    *client.client_error_callback.lock().unwrap() = Some(callback);
+
+    FFIErrorCode::Success as i32
+}
+
+/// Clear the client error callback.
+///
+/// # Safety
+/// - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`.
+#[no_mangle]
+pub unsafe extern "C" fn dash_spv_ffi_client_clear_client_error_callback(
+    client: *mut FFIDashSpvClient,
+) -> i32 {
+    null_check!(client);
+
+    let client = &(*client);
+    *client.client_error_callback.lock().unwrap() = None;
+
+    FFIErrorCode::Success as i32
+}