Skip to content

feat: additional ffi methods for chain tip #145

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

Merged
QuantumExplorer merged 4 commits into from
Sep 17, 2025
Merged

feat: additional ffi methods for chain tip #145

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
21f6ae1
feat: additional ffi
QuantumExplorer Sep 17, 2025
7b3627a
docs
QuantumExplorer Sep 17, 2025
06f8c59
another fix
QuantumExplorer Sep 17, 2025
59f8e14
update docs
QuantumExplorer Sep 17, 2025
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
1 change: 1 addition & 0 deletions dash-spv-ffi/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ log = "0.4"
hex = "0.4"
env_logger = "0.10"
tracing = "0.1"
futures = "0.3"
# Use key-wallet-ffi for all wallet-related FFI types
key-wallet-ffi = { path = "../key-wallet-ffi" }
# Still need these for SPV client internals (not for FFI types)
Expand Down
76 changes: 72 additions & 4 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,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**: 64
**Total Functions**: 68
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

🧩 Analysis chain

Verify function count matches headers

Ensure “Total Functions: 68” reflects the current header set.

🏁 Script executed:

#!/bin/bash
# Compare API doc function count vs generated C header
COUNT_HEADER=$(rg -nP '^\s*(?:int32_t|bool|void|struct [A-Za-z_]\w*\s*\*)\s+dash_spv_ffi_\w+\s*\(' dash-spv-ffi/include/dash_spv_ffi.h | wc -l)
COUNT_DOC=$(rg -n '^\*\*Total Functions\*\*:\s*\d+' dash-spv-ffi/FFI_API.md | sed -E 's/.*: *([0-9]+)/\1/')
echo "Header: $COUNT_HEADER, Doc: $COUNT_DOC"
test "$COUNT_HEADER" = "$COUNT_DOC"

Length of output: 19

Mismatch — update FFI API count or header

dash-spv-ffi/FFI_API.md (line 7) shows "Total Functions: 68" but dash-spv-ffi/include/dash_spv_ffi.h currently exposes 51 dash_spv_ffi_* functions. Update the doc to 51 or regenerate/commit the header to include the missing 17 functions.

🤖 Prompt for AI Agents 
In dash-spv-ffi/FFI_API.md around line 7, the "Total Functions: 68" header is
inconsistent with dash-spv-ffi/include/dash_spv_ffi.h which currently exposes 51
dash_spv_ffi_* functions; either update the markdown count to "Total Functions:
51" or regenerate/commit the header to actually expose the missing 17 functions
so the two stay in sync — choose the correct source of truth (prefer
regenerating the header if the codebase should have 68 functions, otherwise
update the doc), then modify FFI_API.md line 7 to the correct number and commit
the change (or update the header file and run the generator, add/commit the new
header).


## Table of Contents

Expand Down Expand Up @@ -67,11 +67,12 @@ Functions: 26

### Synchronization

Functions: 7
Functions: 8

| Function | Description | Module |
|----------|-------------|--------|
| `dash_spv_ffi_client_cancel_sync` | Cancels the sync operation | client |
| `dash_spv_ffi_client_clear_sync_state` | Clear only the persisted sync-state snapshot | client |
| `dash_spv_ffi_client_get_sync_progress` | Get the current sync progress snapshot | client |
| `dash_spv_ffi_client_is_filter_sync_available` | Check if compact filter sync is currently available | client |
| `dash_spv_ffi_client_sync_to_tip` | Sync the SPV client to the chain tip | client |
Expand Down Expand Up @@ -135,7 +136,7 @@ Functions: 2

### Utility Functions

Functions: 15
Functions: 18

| Function | Description | Module |
|----------|-------------|--------|
Expand All @@ -144,7 +145,10 @@ Functions: 15
| `dash_spv_ffi_checkpoint_before_timestamp` | Get the last checkpoint at or before a given UNIX timestamp (seconds) | checkpoints |
| `dash_spv_ffi_checkpoint_latest` | Get the latest checkpoint for the given network | checkpoints |
| `dash_spv_ffi_checkpoints_between_heights` | Get all checkpoints between two heights (inclusive) | checkpoints |
| `dash_spv_ffi_client_clear_storage` | Clear all persisted SPV storage (headers, filters, metadata, sync state) | client |
| `dash_spv_ffi_client_get_stats` | Get current runtime statistics for the SPV client | client |
| `dash_spv_ffi_client_get_tip_hash` | Get the current chain tip hash (32 bytes) if available | client |
| `dash_spv_ffi_client_get_tip_height` | Get the current chain tip height (absolute) | client |
| `dash_spv_ffi_client_get_wallet_manager` | Get the wallet manager from the SPV client Returns an opaque pointer to FFIW... | client |
| `dash_spv_ffi_client_record_send` | Record that we attempted to send a transaction by its txid | client |
| `dash_spv_ffi_client_rescan_blockchain` | Request a rescan of the blockchain from a given height (not yet implemented) | client |
Expand Down Expand Up @@ -632,7 +636,7 @@ dash_spv_ffi_client_cancel_sync(client: *mut FFIDashSpvClient) -> i32
```

**Description:**
Cancels the sync operation. **Note**: This function currently only stops the SPV client and clears sync callbacks, but does not fully abort the ongoing sync process. The sync operation may continue running in the background until it completes naturally. Full sync cancellation with proper task abortion is not yet implemented. # Safety The client pointer must be valid and non-null. # Returns Returns 0 on success, or an error code on failure.
Cancels the sync operation. This stops the SPV client, clears callbacks, and joins active threads so the sync operation halts immediately. # Safety The client pointer must be valid and non-null. # Returns Returns 0 on success, or an error code on failure.

**Safety:**
The client pointer must be valid and non-null.
Expand All @@ -641,6 +645,22 @@ The client pointer must be valid and non-null.

---

#### `dash_spv_ffi_client_clear_sync_state`

```c
dash_spv_ffi_client_clear_sync_state(client: *mut FFIDashSpvClient,) -> i32
```

**Description:**
Clear only the persisted sync-state snapshot. # Safety - `client` must be a valid, non-null pointer.

**Safety:**
- `client` must be a valid, non-null pointer.

**Module:** `client`

---

#### `dash_spv_ffi_client_get_sync_progress`

```c
Expand Down Expand Up @@ -996,6 +1016,22 @@ Get all checkpoints between two heights (inclusive). Returns an `FFIArray` of `

---

#### `dash_spv_ffi_client_clear_storage`

```c
dash_spv_ffi_client_clear_storage(client: *mut FFIDashSpvClient) -> i32
```

**Description:**
Clear all persisted SPV storage (headers, filters, metadata, sync state). # Safety - `client` must be a valid, non-null pointer.

**Safety:**
- `client` must be a valid, non-null pointer.

**Module:** `client`

---

#### `dash_spv_ffi_client_get_stats`

```c
Expand All @@ -1012,6 +1048,38 @@ Get current runtime statistics for the SPV client. # Safety - `client` must be

---

#### `dash_spv_ffi_client_get_tip_hash`

```c
dash_spv_ffi_client_get_tip_hash(client: *mut FFIDashSpvClient, out_hash: *mut u8,) -> i32
```

**Description:**
Get the current chain tip hash (32 bytes) if available. # Safety - `client` must be a valid, non-null pointer. - `out_hash` must be a valid pointer to a 32-byte buffer.

**Safety:**
- `client` must be a valid, non-null pointer. - `out_hash` must be a valid pointer to a 32-byte buffer.

**Module:** `client`

---

#### `dash_spv_ffi_client_get_tip_height`

```c
dash_spv_ffi_client_get_tip_height(client: *mut FFIDashSpvClient, out_height: *mut u32,) -> i32
```

**Description:**
Get the current chain tip height (absolute). # Safety - `client` must be a valid, non-null pointer. - `out_height` must be a valid, non-null pointer.

**Safety:**
- `client` must be a valid, non-null pointer. - `out_height` must be a valid, non-null pointer.

**Module:** `client`

---

#### `dash_spv_ffi_client_get_wallet_manager`

```c
Expand Down
40 changes: 36 additions & 4 deletions dash-spv-ffi/include/dash_spv_ffi.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -392,10 +392,8 @@ int32_t dash_spv_ffi_client_sync_to_tip_with_progress(struct FFIDashSpvClient *c
/**
* Cancels the sync operation.
*
* **Note**: This function currently only stops the SPV client and clears sync callbacks,
* but does not fully abort the ongoing sync process. The sync operation may continue
* running in the background until it completes naturally. Full sync cancellation with
* proper task abortion is not yet implemented.
* This stops the SPV client, clears callbacks, and joins active threads so the sync
* operation halts immediately.
*
* # Safety
* The client pointer must be valid and non-null.
Expand All @@ -421,6 +419,40 @@ int32_t dash_spv_ffi_client_sync_to_tip_with_progress(struct FFIDashSpvClient *c
*/
struct FFISpvStats *dash_spv_ffi_client_get_stats(struct FFIDashSpvClient *client) ;

/**
* Get the current chain tip hash (32 bytes) if available.
*
* # Safety
* - `client` must be a valid, non-null pointer.
* - `out_hash` must be a valid pointer to a 32-byte buffer.
*/
int32_t dash_spv_ffi_client_get_tip_hash(struct FFIDashSpvClient *client, uint8_t *out_hash) ;

/**
* Get the current chain tip height (absolute).
*
* # Safety
* - `client` must be a valid, non-null pointer.
* - `out_height` must be a valid, non-null pointer.
*/
int32_t dash_spv_ffi_client_get_tip_height(struct FFIDashSpvClient *client, uint32_t *out_height) ;

/**
* Clear all persisted SPV storage (headers, filters, metadata, sync state).
*
* # Safety
* - `client` must be a valid, non-null pointer.
*/
int32_t dash_spv_ffi_client_clear_storage(struct FFIDashSpvClient *client) ;

/**
* Clear only the persisted sync-state snapshot.
*
* # Safety
* - `client` must be a valid, non-null pointer.
*/
int32_t dash_spv_ffi_client_clear_sync_state(struct FFIDashSpvClient *client) ;

/**
* Check if compact filter sync is currently available.
*
Expand Down
Loading
Loading