merge FFI callback setup into dash_spv_ffi_client_run

Pass all event callbacks as a single `FFIEventCallbacks` struct directly
to `run()` instead of requiring separate set_*_callbacks() calls. This
removes 5 Mutex fields from `FFIDashSpvClient` and 10 FFI functions.

Author: xdustinface

dash-spv-ffi/FFI_API.md

@@ -4,17 +4,15 @@ 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**: 49
+**Total Functions**: 39
 
 ## Table of Contents
 
 - [Client Management](#client-management)
 - [Configuration](#configuration)
 - [Synchronization](#synchronization)
-- [Wallet Operations](#wallet-operations)
 - [Transaction Management](#transaction-management)
 - [Platform Integration](#platform-integration)
-- [Event Callbacks](#event-callbacks)
 - [Error Handling](#error-handling)
 - [Utility Functions](#utility-functions)
 
@@ -55,25 +53,14 @@ Functions: 16
 
 ### Synchronization
 
-Functions: 5
+Functions: 3
 
 | Function | Description | Module |
 |----------|-------------|--------|
-| `dash_spv_ffi_client_clear_sync_event_callbacks` | Clear sync event callbacks | client |
 | `dash_spv_ffi_client_get_manager_sync_progress` | Get the current manager-based sync progress | client |
 | `dash_spv_ffi_client_get_sync_progress` | Get the current sync progress snapshot | client |
-| `dash_spv_ffi_client_set_sync_event_callbacks` | Set sync event callbacks for push-based event notifications | client |
 | `dash_spv_ffi_sync_progress_destroy` | Destroy an `FFISyncProgress` object and all its nested pointers | types |
 
-### Wallet Operations
-
-Functions: 2
-
-| Function | Description | Module |
-|----------|-------------|--------|
-| `dash_spv_ffi_client_clear_wallet_event_callbacks` | Clear wallet event callbacks | client |
-| `dash_spv_ffi_client_set_wallet_event_callbacks` | Set wallet event callbacks for push-based event notifications | client |
-
 ### Transaction Management
 
 Functions: 1
@@ -91,19 +78,6 @@ Functions: 2
 | `ffi_dash_spv_get_platform_activation_height` | Gets the platform activation height from the Core chain  # Safety  This... | platform_integration |
 | `ffi_dash_spv_get_quorum_public_key` | Gets a quorum public key from the Core chain  # Safety  This function is... | platform_integration |
 
-### Event Callbacks
-
-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 |
-
 ### Error Handling
 
 Functions: 1
@@ -426,22 +400,6 @@ dash_spv_ffi_config_testnet() -> *mut FFIClientConfig
 
 ### Synchronization - Detailed
 
-#### `dash_spv_ffi_client_clear_sync_event_callbacks`
-
-```c
-dash_spv_ffi_client_clear_sync_event_callbacks(client: *mut FFIDashSpvClient,) -> i32
-```
-
-**Description:**
-Clear sync event callbacks.  # 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_get_manager_sync_progress`
 
 ```c
@@ -474,22 +432,6 @@ Get the current sync progress snapshot.  # Safety - `client` must be a valid, no
 
 ---
 
-#### `dash_spv_ffi_client_set_sync_event_callbacks`
-
-```c
-dash_spv_ffi_client_set_sync_event_callbacks(client: *mut FFIDashSpvClient, callbacks: FFISyncEventCallbacks,) -> i32
-```
-
-**Description:**
-Set sync event callbacks for push-based event notifications.  Call this before calling run(). The callbacks are snapshotted when `dash_spv_ffi_client_run` is called.  # 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 task.
-
-**Module:** `client`
-
----
-
 #### `dash_spv_ffi_sync_progress_destroy`
 
 ```c
@@ -506,40 +448,6 @@ Destroy an `FFISyncProgress` object and all its nested pointers.  # Safety - `pr
 
 ---
 
-### Wallet Operations - Detailed
-
-#### `dash_spv_ffi_client_clear_wallet_event_callbacks`
-
-```c
-dash_spv_ffi_client_clear_wallet_event_callbacks(client: *mut FFIDashSpvClient,) -> i32
-```
-
-**Description:**
-Clear wallet event callbacks.  # 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_set_wallet_event_callbacks`
-
-```c
-dash_spv_ffi_client_set_wallet_event_callbacks(client: *mut FFIDashSpvClient, callbacks: FFIWalletEventCallbacks,) -> i32
-```
-
-**Description:**
-Set wallet event callbacks for push-based event notifications.  Call this before calling run(). The callbacks are snapshotted when `dash_spv_ffi_client_run` is called.  # 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 task.
-
-**Module:** `client`
-
----
-
 ### Transaction Management - Detailed
 
 #### `dash_spv_ffi_client_broadcast_transaction`
@@ -592,104 +500,6 @@ 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
-dash_spv_ffi_client_clear_network_event_callbacks(client: *mut FFIDashSpvClient,) -> i32
-```
-
-**Description:**
-Clear network event callbacks.  # 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_progress_callback`
-
-```c
-dash_spv_ffi_client_clear_progress_callback(client: *mut FFIDashSpvClient,) -> i32
-```
-
-**Description:**
-Clear progress 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_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_client_set_network_event_callbacks(client: *mut FFIDashSpvClient, callbacks: FFINetworkEventCallbacks,) -> i32
-```
-
-**Description:**
-Set network event callbacks for push-based event notifications.  Call this before calling run(). The callbacks are snapshotted when `dash_spv_ffi_client_run` is called.  # 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 task.
-
-**Module:** `client`
-
----
-
-#### `dash_spv_ffi_client_set_progress_callback`
-
-```c
-dash_spv_ffi_client_set_progress_callback(client: *mut FFIDashSpvClient, callback: crate::FFIProgressCallback,) -> i32
-```
-
-**Description:**
-Set progress callback for sync progress updates.  Call this before calling run(). The callback is snapshotted when `dash_spv_ffi_client_run` is called.  # 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 task.
-
-**Module:** `client`
-
----
-
 ### Error Handling - Detailed
 
 #### `dash_spv_ffi_get_last_error`
@@ -787,14 +597,14 @@ The caller must ensure that: - The client pointer is valid - The returned pointe
 #### `dash_spv_ffi_client_run`
 
 ```c
-dash_spv_ffi_client_run(client: *mut FFIDashSpvClient) -> i32
+dash_spv_ffi_client_run(client: *mut FFIDashSpvClient, callbacks: FFIEventCallbacks,) -> i32
 ```
 
 **Description:**
-Start the SPV client and begin syncing in the background.  Creates an event handler from the currently configured callbacks and passes it to the library's `run()` method, which manages all channel subscriptions and monitoring tasks internally. Returns immediately after spawning.  Configure callbacks before calling `run()` via `set_sync_event_callbacks`, `set_network_event_callbacks`, `set_wallet_event_callbacks`, etc.  # 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.  Accepts all event callbacks as a single struct and passes them to the library's `run()` method, which manages channel subscriptions and monitoring tasks internally. Returns immediately after spawning.  # Safety - `client` must be a valid, non-null pointer to a created client. - The `callbacks` struct and its `user_data` pointers must remain valid until `dash_spv_ffi_client_stop` or `dash_spv_ffi_client_destroy` is called.  # Returns 0 on success, error code on failure.
 
 **Safety:**
-- `client` must be a valid, non-null pointer to a created client.
+- `client` must be a valid, non-null pointer to a created client. - The `callbacks` struct and its `user_data` pointers must remain valid until `dash_spv_ffi_client_stop` or `dash_spv_ffi_client_destroy` is called.
 
 **Module:** `client`
 

dash-spv-ffi/src/bin/ffi_cli.rs

@@ -403,84 +403,50 @@ fn main() {
             dash_spv_ffi_wallet_manager_free(wallet_manager);
         }
 
-        // Set up event callbacks
-        let sync_callbacks = FFISyncEventCallbacks {
-            on_sync_start: Some(on_sync_start),
-            on_block_headers_stored: Some(on_block_headers_stored),
-            on_block_header_sync_complete: Some(on_block_header_sync_complete),
-            on_filter_headers_stored: Some(on_filter_headers_stored),
-            on_filter_headers_sync_complete: Some(on_filter_headers_sync_complete),
-            on_filters_stored: Some(on_filters_stored),
-            on_filters_sync_complete: Some(on_filters_sync_complete),
-            on_blocks_needed: Some(on_blocks_needed),
-            on_block_processed: Some(on_block_processed),
-            on_masternode_state_updated: Some(on_masternode_state_updated),
-            on_chainlock_received: Some(on_chainlock_received),
-            on_instantlock_received: Some(on_instantlock_received),
-            on_manager_error: Some(on_manager_error),
-            on_sync_complete: Some(on_sync_complete),
-            user_data: ptr::null_mut(),
+        // Build all event callbacks in a single struct
+        let callbacks = FFIEventCallbacks {
+            sync: FFISyncEventCallbacks {
+                on_sync_start: Some(on_sync_start),
+                on_block_headers_stored: Some(on_block_headers_stored),
+                on_block_header_sync_complete: Some(on_block_header_sync_complete),
+                on_filter_headers_stored: Some(on_filter_headers_stored),
+                on_filter_headers_sync_complete: Some(on_filter_headers_sync_complete),
+                on_filters_stored: Some(on_filters_stored),
+                on_filters_sync_complete: Some(on_filters_sync_complete),
+                on_blocks_needed: Some(on_blocks_needed),
+                on_block_processed: Some(on_block_processed),
+                on_masternode_state_updated: Some(on_masternode_state_updated),
+                on_chainlock_received: Some(on_chainlock_received),
+                on_instantlock_received: Some(on_instantlock_received),
+                on_manager_error: Some(on_manager_error),
+                on_sync_complete: Some(on_sync_complete),
+                user_data: ptr::null_mut(),
+            },
+            network: FFINetworkEventCallbacks {
+                on_peer_connected: Some(on_peer_connected),
+                on_peer_disconnected: Some(on_peer_disconnected),
+                on_peers_updated: Some(on_peers_updated),
+                user_data: ptr::null_mut(),
+            },
+            progress: FFIProgressCallback {
+                on_progress: Some(on_progress_update),
+                user_data: ptr::null_mut(),
+            },
+            wallet: FFIWalletEventCallbacks {
+                on_transaction_received: Some(on_transaction_received),
+                on_balance_updated: Some(on_balance_updated),
+                user_data: ptr::null_mut(),
+            },
+            error: FFIClientErrorCallback {
+                on_error: None,
+                user_data: ptr::null_mut(),
+            },
         };
 
-        let network_callbacks = FFINetworkEventCallbacks {
-            on_peer_connected: Some(on_peer_connected),
-            on_peer_disconnected: Some(on_peer_disconnected),
-            on_peers_updated: Some(on_peers_updated),
-            user_data: ptr::null_mut(),
-        };
-
-        let wallet_callbacks = FFIWalletEventCallbacks {
-            on_transaction_received: Some(on_transaction_received),
-            on_balance_updated: Some(on_balance_updated),
-            user_data: ptr::null_mut(),
-        };
-
-        let rc = dash_spv_ffi_client_set_sync_event_callbacks(client, sync_callbacks);
-        if rc != FFIErrorCode::Success as i32 {
-            eprintln!(
-                "Failed to set sync callbacks: {}",
-                ffi_string_to_rust(dash_spv_ffi_get_last_error())
-            );
-            std::process::exit(1);
-        }
-
-        let rc = dash_spv_ffi_client_set_network_event_callbacks(client, network_callbacks);
-        if rc != FFIErrorCode::Success as i32 {
-            eprintln!(
-                "Failed to set network callbacks: {}",
-                ffi_string_to_rust(dash_spv_ffi_get_last_error())
-            );
-            std::process::exit(1);
-        }
-
-        let rc = dash_spv_ffi_client_set_wallet_event_callbacks(client, wallet_callbacks);
-        if rc != FFIErrorCode::Success as i32 {
-            eprintln!(
-                "Failed to set wallet callbacks: {}",
-                ffi_string_to_rust(dash_spv_ffi_get_last_error())
-            );
-            std::process::exit(1);
-        }
-
-        // Set up progress callback
-        let progress_callback = FFIProgressCallback {
-            on_progress: Some(on_progress_update),
-            user_data: ptr::null_mut(),
-        };
-
-        let rc = dash_spv_ffi_client_set_progress_callback(client, progress_callback);
-        if rc != FFIErrorCode::Success as i32 {
-            eprintln!(
-                "Failed to set progress callback: {}",
-                ffi_string_to_rust(dash_spv_ffi_get_last_error())
-            );
-            std::process::exit(1);
-        }
-
         println!("Event and progress callbacks configured, starting sync...");
 
         // Run client - starts sync in background and returns immediately
-        let rc = dash_spv_ffi_client_run(client);
+        let rc = dash_spv_ffi_client_run(client, callbacks);
         if rc != FFIErrorCode::Success as i32 {
             eprintln!("Client run failed: {}", ffi_string_to_rust(dash_spv_ffi_get_last_error()));
             std::process::exit(1);