refactor: replace FFI OS threads with tokio tasks

dash-spv-ffi/FFI_API.md

@@ -488,10 +488,10 @@ dash_spv_ffi_client_set_sync_event_callbacks(client: *mut FFIDashSpvClient, call
 ```
 
 **Description:**
-Set sync event callbacks for push-based event notifications.  The monitoring thread is spawned when `dash_spv_ffi_client_run` is called. Call this before calling run().  # Safety - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared. - Callbacks must be thread-safe as they may be called from a background thread.
+Set sync event callbacks for push-based event notifications.  The monitoring task is spawned when `dash_spv_ffi_client_run` is called. Call this before calling run().  # Safety - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared. - Callbacks must be thread-safe as they may be called from a background task.
 
 **Safety:**
-- `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared. - Callbacks must be thread-safe as they may be called from a background thread.
+- `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared. - Callbacks must be thread-safe as they may be called from a background task.
 
 **Module:** `client`
 
@@ -554,10 +554,10 @@ dash_spv_ffi_client_set_wallet_event_callbacks(client: *mut FFIDashSpvClient, ca
 ```
 
 **Description:**
-Set wallet event callbacks for push-based event notifications.  The monitoring thread is spawned when `dash_spv_ffi_client_run` is called. Call this before calling run().  # Safety - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared. - Callbacks must be thread-safe as they may be called from a background thread.
+Set wallet event callbacks for push-based event notifications.  The monitoring task is spawned when `dash_spv_ffi_client_run` is called. Call this before calling run().  # Safety - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared. - Callbacks must be thread-safe as they may be called from a background task.
 
 **Safety:**
-- `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared. - Callbacks must be thread-safe as they may be called from a background thread.
+- `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared. - Callbacks must be thread-safe as they may be called from a background task.
 
 **Module:** `client`
 
@@ -638,10 +638,10 @@ dash_spv_ffi_client_set_network_event_callbacks(client: *mut FFIDashSpvClient, c
 ```
 
 **Description:**
-Set network event callbacks for push-based event notifications.  The monitoring thread is spawned when `dash_spv_ffi_client_run` is called. Call this before calling run().  # Safety - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared. - Callbacks must be thread-safe as they may be called from a background thread.
+Set network event callbacks for push-based event notifications.  The monitoring task is spawned when `dash_spv_ffi_client_run` is called. Call this before calling run().  # Safety - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared. - Callbacks must be thread-safe as they may be called from a background task.
 
 **Safety:**
-- `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared. - Callbacks must be thread-safe as they may be called from a background thread.
+- `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared. - Callbacks must be thread-safe as they may be called from a background task.
 
 **Module:** `client`
 
@@ -654,10 +654,10 @@ dash_spv_ffi_client_set_progress_callback(client: *mut FFIDashSpvClient, callbac
 ```
 
 **Description:**
-Set progress callback for sync progress updates.  The monitoring thread is spawned when `dash_spv_ffi_client_run` is called. Call this before calling run().  # 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.
+Set progress callback for sync progress updates.  The monitoring task is spawned when `dash_spv_ffi_client_run` is called. Call this before calling run().  # 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 task.
 
 **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.
+- `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 task.
 
 **Module:** `client`
 
@@ -764,7 +764,7 @@ dash_spv_ffi_client_run(client: *mut FFIDashSpvClient) -> i32
 ```
 
 **Description:**
-Start the SPV client and begin syncing in the background.  This is the streamlined entry point that combines `start()` and continuous monitoring into a single non-blocking call. Use event callbacks (set via `set_sync_event_callbacks`, `set_network_event_callbacks`, `set_wallet_event_callbacks`) to receive notifications about sync progress, peer connections, and wallet activity.  Workflow: 1. Configure event callbacks before calling `run()` 2. Call `run()` - it returns immediately after spawning background sync threads 3. Receive notifications via callbacks as sync progresses 4. Call `stop()` when done  # Safety - `client` must be a valid, non-null pointer to a created client.  # Returns 0 on success, error code on failure.
+Start the SPV client and begin syncing in the background.  This is the streamlined entry point that combines `start()` and continuous monitoring into a single non-blocking call. Use event callbacks (set via `set_sync_event_callbacks`, `set_network_event_callbacks`, `set_wallet_event_callbacks`) to receive notifications about sync progress, peer connections, and wallet activity.  Workflow: 1. Configure event callbacks before calling `run()` 2. Call `run()` - it returns immediately after spawning background tasks 3. Receive notifications via callbacks as sync progresses 4. Call `stop()` when done  # Safety - `client` must be a valid, non-null pointer to a created client.  # Returns 0 on success, error code on failure.
 
 **Safety:**
 - `client` must be a valid, non-null pointer to a created client.

dash-spv-ffi/include/dash_spv_ffi.h

@@ -494,7 +494,7 @@ int32_t dash_spv_ffi_client_update_config(struct FFIDashSpvClient *client,
  *
  * Workflow:
  * 1. Configure event callbacks before calling `run()`
- * 2. Call `run()` - it returns immediately after spawning background sync threads
+ * 2. Call `run()` - it returns immediately after spawning background tasks
  * 3. Receive notifications via callbacks as sync progresses
  * 4. Call `stop()` when done
  *
@@ -587,13 +587,13 @@ struct FFISyncProgress *dash_spv_ffi_client_get_manager_sync_progress(struct FFI
 /**
  * Set sync event callbacks for push-based event notifications.
  *
- * The monitoring thread is spawned when `dash_spv_ffi_client_run` is called.
+ * The monitoring task is spawned when `dash_spv_ffi_client_run` is called.
  * Call this before calling run().
  *
  * # Safety
  * - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`.
  * - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared.
- * - Callbacks must be thread-safe as they may be called from a background thread.
+ * - Callbacks must be thread-safe as they may be called from a background task.
  */
 
 int32_t dash_spv_ffi_client_set_sync_event_callbacks(struct FFIDashSpvClient *client,
@@ -611,13 +611,13 @@ int32_t dash_spv_ffi_client_set_sync_event_callbacks(struct FFIDashSpvClient *cl
 /**
  * Set network event callbacks for push-based event notifications.
  *
- * The monitoring thread is spawned when `dash_spv_ffi_client_run` is called.
+ * The monitoring task is spawned when `dash_spv_ffi_client_run` is called.
  * Call this before calling run().
  *
  * # Safety
  * - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`.
  * - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared.
- * - Callbacks must be thread-safe as they may be called from a background thread.
+ * - Callbacks must be thread-safe as they may be called from a background task.
  */
 
 int32_t dash_spv_ffi_client_set_network_event_callbacks(struct FFIDashSpvClient *client,
@@ -635,13 +635,13 @@ int32_t dash_spv_ffi_client_set_network_event_callbacks(struct FFIDashSpvClient
 /**
  * Set wallet event callbacks for push-based event notifications.
  *
- * The monitoring thread is spawned when `dash_spv_ffi_client_run` is called.
+ * The monitoring task is spawned when `dash_spv_ffi_client_run` is called.
  * Call this before calling run().
  *
  * # Safety
  * - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`.
  * - The `callbacks` struct and its `user_data` must remain valid until callbacks are cleared.
- * - Callbacks must be thread-safe as they may be called from a background thread.
+ * - Callbacks must be thread-safe as they may be called from a background task.
  */
 
 int32_t dash_spv_ffi_client_set_wallet_event_callbacks(struct FFIDashSpvClient *client,
@@ -659,13 +659,13 @@ int32_t dash_spv_ffi_client_set_wallet_event_callbacks(struct FFIDashSpvClient *
 /**
  * Set progress callback for sync progress updates.
  *
- * The monitoring thread is spawned when `dash_spv_ffi_client_run` is called.
+ * The monitoring task is spawned when `dash_spv_ffi_client_run` is called.
  * Call this before calling run().
  *
  * # 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.
+ * - The callback must be thread-safe as it may be called from a background task.
  */
 
 int32_t dash_spv_ffi_client_set_progress_callback(struct FFIDashSpvClient *client,

dash-spv-ffi/src/callbacks.rs

@@ -56,6 +56,7 @@ pub type OnProgressUpdateCallback =
 
 /// Progress callback configuration.
 #[repr(C)]
+#[derive(Clone)]
 pub struct FFIProgressCallback {
     /// Callback function for progress updates.
     pub on_progress: OnProgressUpdateCallback,
@@ -218,6 +219,7 @@ pub type OnSyncCompleteCallback = Option<extern "C" fn(header_tip: u32, user_dat
 /// borrowed and only valid for the duration of the callback invocation.
 /// Callers must memcpy/duplicate any data they need to retain.
 #[repr(C)]
+#[derive(Clone)]
 pub struct FFISyncEventCallbacks {
     pub on_sync_start: OnSyncStartCallback,
     pub on_block_headers_stored: OnBlockHeadersStoredCallback,
@@ -448,6 +450,7 @@ pub type OnPeersUpdatedCallback =
 /// borrowed and only valid for the duration of the callback invocation.
 /// Callers must copy any data they need to retain.
 #[repr(C)]
+#[derive(Clone)]
 pub struct FFINetworkEventCallbacks {
     pub on_peer_connected: OnPeerConnectedCallback,
     pub on_peer_disconnected: OnPeerDisconnectedCallback,
@@ -549,6 +552,7 @@ pub type OnBalanceUpdatedCallback = Option<
 /// are borrowed and only valid for the duration of the callback invocation.
 /// Callers must copy any data they need to retain.
 #[repr(C)]
+#[derive(Clone)]
 pub struct FFIWalletEventCallbacks {
     pub on_transaction_received: OnTransactionReceivedCallback,
     pub on_balance_updated: OnBalanceUpdatedCallback,