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**: 48
+**Total Functions**: 50
 
 ## Table of Contents
 
@@ -86,12 +86,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 |
 
@@ -599,6 +601,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
@@ -631,6 +649,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

@@ -434,6 +434,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
  */
@@ -680,6 +697,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

@@ -573,6 +573,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;
@@ -120,6 +120,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.
@@ -179,6 +180,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))
         }
@@ -313,18 +315,7 @@ pub unsafe extern "C" fn dash_spv_ffi_client_run(client: *mut FFIDashSpvClient)
 
     let client = &(*client);
 
-    tracing::info!("dash_spv_ffi_client_run: starting client");
-
-    // Start the client first
-    let start_result = client.runtime.block_on(async { client.inner.start().await });
-
-    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");
+    tracing::info!("dash_spv_ffi_client_run: setting up event monitoring");
 
     let shutdown_token = client.shutdown_token.clone();
 
@@ -386,13 +377,27 @@ pub unsafe extern "C" fn dash_spv_ffi_client_run(client: *mut FFIDashSpvClient)
         ));
     }
 
-    // Spawn the sync monitoring task
+    let error_callback = client.client_error_callback.clone();
     let spv_client = client.inner.clone();
     tasks.push(client.runtime.spawn(async move {
         tracing::debug!("Sync task: 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());
+            }
+            return;
+        }
+
         if let Err(e) = spv_client.monitor_network(shutdown_token).await {
             tracing::error!("Sync task: 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 task: exiting");
@@ -714,3 +719,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
+}