Skip to content

fix: handle and propagate errors in event channel monitors #573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
xdustinface wants to merge 4 commits into
base: refactor/move-callbacks-to-crates
Choose a base branch
from
Draft

fix: handle and propagate errors in event channel monitors #573

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f35d764
refactor: move event callback dispatch into `dash-spv` client
xdustinface Mar 22, 2026
2eab339
add `LoggingEventHandler` to CLI binary
xdustinface Mar 15, 2026
becff66
merge FFI callback setup into `dash_spv_ffi_client_run`
xdustinface Mar 15, 2026
1f3f4c0
fix: handle and propagate errors in event channel monitors
xdustinface Mar 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
200 changes: 5 additions & 195 deletions dash-spv-ffi/FFI_API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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. 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 task.

**Module:** `client`

---

#### `dash_spv_ffi_sync_progress_destroy`

```c
Expand All @@ -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. 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 task.

**Module:** `client`

---

### Transaction Management - Detailed

#### `dash_spv_ffi_client_broadcast_transaction`
Expand Down Expand Up @@ -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. 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 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. 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 task.

**Module:** `client`

---

### Error Handling - Detailed

#### `dash_spv_ffi_get_last_error`
Expand Down Expand Up @@ -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. Subscribes to events, spawns monitoring threads, then spawns a background thread that calls `run()` (which handles start + sync loop + stop internally). Returns immediately after spawning. Use event callbacks (set via `set_sync_event_callbacks`, `set_network_event_callbacks`, `set_wallet_event_callbacks`) to receive notifications. Configure callbacks before calling `run()`. # 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`

Expand Down
112 changes: 39 additions & 73 deletions dash-spv-ffi/src/bin/ffi_cli.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
Loading
Loading