diff --git a/.gitignore b/.gitignore index 78c251eba..4aa7ddd2e 100644 --- a/.gitignore +++ b/.gitignore @@ -46,5 +46,9 @@ cobertura.xml # Python __pycache__/ +# Generated FFI headers (produced by build.rs via cbindgen) +dash-spv-ffi/include/ +key-wallet-ffi/include/ + # Build scripts artifacts *.log diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index bfb03fd2d..7ad1fec2f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -62,21 +62,20 @@ repos: types: [rust] pass_filenames: false - # ============================================================================ - # SLOW CHECKS - Run on git push only. - # ============================================================================ - - - repo: local - hooks: - id: verify-ffi name: verify FFI - description: Verify FFI headers and documentation are up to date + description: Verify FFI documentation is up to date entry: contrib/verify_ffi.py language: python pass_filenames: false files: ^(key-wallet-ffi|dash-spv-ffi)/.*\.(rs|toml|py)$ - stages: [pre-push, manual] + # ============================================================================ + # SLOW CHECKS - Run on git push only. + # ============================================================================ + + - repo: local + hooks: - id: clippy name: clippy (workspace strict) description: Strict clippy on entire workspace - deny all warnings diff --git a/contrib/verify_ffi.py b/contrib/verify_ffi.py index e591b4460..abbbb374a 100755 --- a/contrib/verify_ffi.py +++ b/contrib/verify_ffi.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Verify that FFI headers and documentation are up to date.""" +"""Verify that FFI documentation is up to date.""" import subprocess import sys @@ -9,24 +9,6 @@ FFI_CRATES = ["key-wallet-ffi", "dash-spv-ffi"] -def build_ffi_crates(repo_root: Path) -> bool: - """Build all FFI crates to regenerate headers.""" - print(" Building FFI crates...") - result = subprocess.run( - ["cargo", "build", "--quiet", "--target-dir", "target/verify-ffi"] - + [f"-p={crate}" for crate in FFI_CRATES], - cwd=repo_root, - capture_output=True, - text=True - ) - if result.returncode != 0: - print("Build failed:", file=sys.stderr) - if result.stderr: - print(result.stderr, file=sys.stderr) - return False - return True - - def generate_ffi_docs(crate_dir: Path) -> tuple[str, int, str]: """Generate FFI documentation for a crate.""" print(f" Generating {crate_dir.name} docs...") @@ -46,11 +28,7 @@ def main(): repo_root = Path(__file__).parent.parent ffi_crate_dirs = [repo_root / crate for crate in FFI_CRATES] - print("Regenerating FFI headers and documentation") - - # Build all FFI crates first - if not build_ffi_crates(repo_root): - sys.exit(1) + print("Regenerating FFI documentation") # Generate docs in parallel with ThreadPoolExecutor(max_workers=2) as executor: @@ -68,13 +46,6 @@ def main(): print(" Generation complete, checking for changes...") - # Check if headers changed - headers_result = subprocess.run( - ["git", "diff", "--exit-code", "--quiet", "--", - "key-wallet-ffi/include/", "dash-spv-ffi/include/"], - cwd=repo_root - ) - # Check if docs changed docs_result = subprocess.run( ["git", "diff", "--exit-code", "--quiet", "--", @@ -82,34 +53,19 @@ def main(): cwd=repo_root ) - headers_changed = headers_result.returncode != 0 - docs_changed = docs_result.returncode != 0 - - if headers_changed or docs_changed: + if docs_result.returncode != 0: + print() + print("FFI documentation is out of date!\n") + print("Documentation changes detected:") + subprocess.run( + ["git", "--no-pager", "diff", "--", + "key-wallet-ffi/FFI_API.md", "dash-spv-ffi/FFI_API.md"], + cwd=repo_root + ) print() - if headers_changed: - print("FFI headers are out of date!\n") - print("Header changes detected:") - subprocess.run( - ["git", "--no-pager", "diff", "--", - "key-wallet-ffi/include/", "dash-spv-ffi/include/"], - cwd=repo_root - ) - print() - - if docs_changed: - print("FFI documentation is out of date!\n") - print("Documentation changes detected:") - subprocess.run( - ["git", "--no-pager", "diff", "--", - "key-wallet-ffi/FFI_API.md", "dash-spv-ffi/FFI_API.md"], - cwd=repo_root - ) - print() - sys.exit(1) - print("FFI headers and documentation are up to date") + print("FFI documentation is up to date") if __name__ == "__main__": diff --git a/dash-spv-ffi/CLAUDE.md b/dash-spv-ffi/CLAUDE.md index 6cb8fac28..66ce8e7ba 100644 --- a/dash-spv-ffi/CLAUDE.md +++ b/dash-spv-ffi/CLAUDE.md @@ -22,10 +22,7 @@ cargo build --release --target aarch64-apple-ios-sim ``` ### Header Generation -The C header is auto-generated by the build script. To regenerate manually: -```bash -cbindgen --config cbindgen.toml --crate dash-spv-ffi --output include/dash_spv_ffi.h -``` +The C header (`include/dash_spv_ffi.h`) is auto-generated by `build.rs` during `cargo build` and is gitignored. ## Testing diff --git a/dash-spv-ffi/Makefile b/dash-spv-ffi/Makefile index ed855d91e..24417a3c2 100644 --- a/dash-spv-ffi/Makefile +++ b/dash-spv-ffi/Makefile @@ -14,12 +14,6 @@ test: # Clean build artifacts clean: cargo clean - rm -f include/dash_spv_ffi.h - -# Generate C header -header: - cargo build --release - @echo "Generated header at include/dash_spv_ffi.h" # Update FFI documentation update-docs: @@ -32,7 +26,7 @@ check-docs: @bash scripts/check_ffi_docs.sh # Generate all documentation -docs: header update-docs +docs: update-docs @echo "All documentation generated" # Build for iOS @@ -42,7 +36,7 @@ ios: cargo build --release --target x86_64-apple-ios # Full build with documentation -full: clean build header update-docs +full: clean build update-docs @echo "Full build complete with documentation" # Help @@ -51,7 +45,6 @@ help: @echo " make build - Build the library" @echo " make test - Run tests" @echo " make clean - Clean build artifacts" - @echo " make header - Generate C header" @echo " make update-docs - Update FFI API documentation" @echo " make check-docs - Check if FFI docs are up to date" @echo " make docs - Generate all documentation" diff --git a/dash-spv-ffi/dash_spv_ffi.h b/dash-spv-ffi/dash_spv_ffi.h deleted file mode 100644 index 2099b6a4c..000000000 --- a/dash-spv-ffi/dash_spv_ffi.h +++ /dev/null @@ -1,995 +0,0 @@ -/* dash-spv-ffi C bindings - Auto-generated by cbindgen */ - -#ifndef DASH_SPV_FFI_H -#define DASH_SPV_FFI_H - -/* Generated with cbindgen:0.29.0 */ - -/* Warning: This file is auto-generated by cbindgen. Do not modify manually. */ - -#include -#include -#include -#include - -#ifdef __cplusplus -namespace dash_spv_ffi { -#endif // __cplusplus - -typedef enum FFIMempoolStrategy { - FetchAll = 0, - BloomFilter = 1, - Selective = 2, -} FFIMempoolStrategy; - -typedef enum FFISyncStage { - Connecting = 0, - QueryingHeight = 1, - Downloading = 2, - Validating = 3, - Storing = 4, - DownloadingFilterHeaders = 5, - DownloadingFilters = 6, - DownloadingBlocks = 7, - Complete = 8, - Failed = 9, -} FFISyncStage; - -typedef enum DashSpvValidationMode { - None = 0, - Basic = 1, - Full = 2, -} DashSpvValidationMode; - -typedef struct FFIDashSpvClient FFIDashSpvClient; - -/** - * FFI-safe array that transfers ownership of memory to the C caller. - * - * # Safety - * - * This struct represents memory that has been allocated by Rust but ownership - * has been transferred to the C caller. The caller is responsible for: - * - Not accessing the memory after it has been freed - * - Calling `dash_spv_ffi_array_destroy` to properly deallocate the memory - * - Ensuring the data, len, and capacity fields remain consistent - */ -typedef struct FFIArray { - void *data; - uintptr_t len; - uintptr_t capacity; - uintptr_t elem_size; - uintptr_t elem_align; -} FFIArray; - -typedef struct FFIClientConfig { - void *inner; - uint32_t worker_threads; - -} FFIClientConfig; - -typedef struct FFIString { - char *ptr; - uintptr_t length; -} FFIString; - -typedef struct FFISyncProgress { - uint32_t header_height; - uint32_t filter_header_height; - uint32_t masternode_height; - uint32_t peer_count; - bool filter_sync_available; - uint32_t filters_downloaded; - uint32_t last_synced_filter_height; -} FFISyncProgress; - -typedef struct FFIDetailedSyncProgress { - uint32_t total_height; - double percentage; - double headers_per_second; - int64_t estimated_seconds_remaining; - enum FFISyncStage stage; - struct FFIString stage_message; - struct FFISyncProgress overview; - uint64_t total_headers; - int64_t sync_start_timestamp; -} FFIDetailedSyncProgress; - -typedef struct FFISpvStats { - uint32_t connected_peers; - uint32_t total_peers; - uint32_t header_height; - uint32_t filter_height; - uint64_t headers_downloaded; - uint64_t filter_headers_downloaded; - uint64_t filters_downloaded; - uint64_t filters_matched; - uint64_t blocks_processed; - uint64_t bytes_received; - uint64_t bytes_sent; - uint64_t uptime; -} FFISpvStats; - -typedef void (*BlockCallback)(uint32_t height, const uint8_t (*hash)[32], void *user_data); - -typedef void (*TransactionCallback)(const uint8_t (*txid)[32], - bool confirmed, - int64_t amount, - const char *addresses, - uint32_t block_height, - void *user_data); - -typedef void (*BalanceCallback)(uint64_t confirmed, uint64_t unconfirmed, void *user_data); - -typedef void (*MempoolTransactionCallback)(const uint8_t (*txid)[32], - int64_t amount, - const char *addresses, - bool is_instant_send, - void *user_data); - -typedef void (*MempoolConfirmedCallback)(const uint8_t (*txid)[32], - uint32_t block_height, - const uint8_t (*block_hash)[32], - void *user_data); - -typedef void (*MempoolRemovedCallback)(const uint8_t (*txid)[32], uint8_t reason, void *user_data); - -typedef void (*CompactFilterMatchedCallback)(const uint8_t (*block_hash)[32], - const char *matched_scripts, - const char *wallet_id, - void *user_data); - -typedef void (*WalletTransactionCallback)(const char *wallet_id, - uint32_t account_index, - const uint8_t (*txid)[32], - bool confirmed, - int64_t amount, - const char *addresses, - uint32_t block_height, - bool is_ours, - void *user_data); - -typedef struct FFIEventCallbacks { - BlockCallback on_block; - TransactionCallback on_transaction; - BalanceCallback on_balance_update; - MempoolTransactionCallback on_mempool_transaction_added; - MempoolConfirmedCallback on_mempool_transaction_confirmed; - MempoolRemovedCallback on_mempool_transaction_removed; - CompactFilterMatchedCallback on_compact_filter_matched; - WalletTransactionCallback on_wallet_transaction; - void *user_data; -} FFIEventCallbacks; - -/** - * Handle for Core SDK that can be passed to Platform SDK - */ -typedef struct CoreSDKHandle { - struct FFIDashSpvClient *client; -} CoreSDKHandle; - -/** - * FFIResult type for error handling - */ -typedef struct FFIResult { - int32_t error_code; - const char *error_message; -} FFIResult; - -/** - * FFI-safe representation of an unconfirmed transaction - * - * # Safety - * - * This struct contains raw pointers that must be properly managed: - * - * - `raw_tx`: A pointer to the raw transaction bytes. The caller is responsible for: - * - Allocating this memory before passing it to Rust - * - Ensuring the pointer remains valid for the lifetime of this struct - * - Freeing the memory after use with `dash_spv_ffi_unconfirmed_transaction_destroy_raw_tx` - * - * - `addresses`: A pointer to an array of FFIString objects. The caller is responsible for: - * - Allocating this array before passing it to Rust - * - Ensuring the pointer remains valid for the lifetime of this struct - * - Freeing each FFIString in the array with `dash_spv_ffi_string_destroy` - * - Freeing the array itself after use with `dash_spv_ffi_unconfirmed_transaction_destroy_addresses` - * - * Use `dash_spv_ffi_unconfirmed_transaction_destroy` to safely clean up all resources - * associated with this struct. - */ -typedef struct FFIUnconfirmedTransaction { - struct FFIString txid; - uint8_t *raw_tx; - uintptr_t raw_tx_len; - int64_t amount; - uint64_t fee; - bool is_instant_send; - bool is_outgoing; - struct FFIString *addresses; - uintptr_t addresses_len; -} FFIUnconfirmedTransaction; - -#ifdef __cplusplus -extern "C" { -#endif // __cplusplus - -/** - * Get the latest checkpoint for the given network. - * - * # Safety - * - `out_height` must be a valid pointer to a `u32`. - * - `out_hash` must point to at least 32 writable bytes. - */ - -int32_t dash_spv_ffi_checkpoint_latest(FFINetwork network, - uint32_t *out_height, - uint8_t *out_hash) -; - -/** - * Get the last checkpoint at or before a given height. - * - * # Safety - * - `out_height` must be a valid pointer to a `u32`. - * - `out_hash` must point to at least 32 writable bytes. - */ - -int32_t dash_spv_ffi_checkpoint_before_height(FFINetwork network, - uint32_t height, - uint32_t *out_height, - uint8_t *out_hash) -; - -/** - * Get the last checkpoint at or before a given UNIX timestamp (seconds). - * - * # Safety - * - `out_height` must be a valid pointer to a `u32`. - * - `out_hash` must point to at least 32 writable bytes. - */ - -int32_t dash_spv_ffi_checkpoint_before_timestamp(FFINetwork network, - uint32_t timestamp, - uint32_t *out_height, - uint8_t *out_hash) -; - -/** - * Get all checkpoints between two heights (inclusive). - * - * Returns an `FFIArray` of `FFICheckpoint` items. The caller owns the memory and - * must free the array buffer using `dash_spv_ffi_array_destroy` when done. - */ - -struct FFIArray dash_spv_ffi_checkpoints_between_heights(FFINetwork network, - uint32_t start_height, - uint32_t end_height) -; - -/** - * Create a new SPV client and return an opaque pointer. - * - * # Safety - * - `config` must be a valid, non-null pointer for the duration of the call. - * - The returned pointer must be freed with `dash_spv_ffi_client_destroy`. - */ - struct FFIDashSpvClient *dash_spv_ffi_client_new(const struct FFIClientConfig *config) ; - -/** - * Drain pending events and invoke configured callbacks (non-blocking). - * - * # Safety - * - `client` must be a valid, non-null pointer. - */ - int32_t dash_spv_ffi_client_drain_events(struct FFIDashSpvClient *client) ; - -/** - * Update the running client's configuration. - * - * # Safety - * - `client` must be a valid pointer to an `FFIDashSpvClient`. - * - `config` must be a valid pointer to an `FFIClientConfig`. - * - The network in `config` must match the client's network; changing networks at runtime is not supported. - */ - -int32_t dash_spv_ffi_client_update_config(struct FFIDashSpvClient *client, - const struct FFIClientConfig *config) -; - -/** - * Start the SPV client. - * - * # Safety - * - `client` must be a valid, non-null pointer to a created client. - */ - int32_t dash_spv_ffi_client_start(struct FFIDashSpvClient *client) ; - -/** - * Stop the SPV client. - * - * # Safety - * - `client` must be a valid, non-null pointer to a created client. - */ - int32_t dash_spv_ffi_client_stop(struct FFIDashSpvClient *client) ; - -/** - * Sync the SPV client to the chain tip. - * - * # Safety - * - * This function is unsafe because: - * - `client` must be a valid pointer to an initialized `FFIDashSpvClient` - * - `user_data` must satisfy thread safety requirements: - * - If non-null, it must point to data that is safe to access from multiple threads - * - The caller must ensure proper synchronization if the data is mutable - * - The data must remain valid for the entire duration of the sync operation - * - `completion_callback` must be thread-safe and can be called from any thread - * - * # Parameters - * - * - `client`: Pointer to the SPV client - * - `completion_callback`: Optional callback invoked on completion - * - `user_data`: Optional user data pointer passed to callbacks - * - * # Returns - * - * 0 on success, error code on failure - */ - -int32_t dash_spv_ffi_client_start_sync(struct FFIDashSpvClient *client, - void (*completion_callback)(bool, const char*, void*), - void *user_data) -; - -/** - * Performs a test synchronization of the SPV client - * - * # Parameters - * - `client`: Pointer to an FFIDashSpvClient instance - * - * # Returns - * - `0` on success - * - Negative error code on failure - * - * # Safety - * This function is unsafe because it dereferences a raw pointer. - * The caller must ensure that the client pointer is valid. - */ - int32_t dash_spv_ffi_client_test_sync(struct FFIDashSpvClient *client) ; - -/** - * Sync the SPV client to the chain tip with detailed progress updates. - * - * # Safety - * - * This function is unsafe because: - * - `client` must be a valid pointer to an initialized `FFIDashSpvClient` - * - `user_data` must satisfy thread safety requirements: - * - If non-null, it must point to data that is safe to access from multiple threads - * - The caller must ensure proper synchronization if the data is mutable - * - The data must remain valid for the entire duration of the sync operation - * - Both `progress_callback` and `completion_callback` must be thread-safe and can be called from any thread - * - * # Parameters - * - * - `client`: Pointer to the SPV client - * - `progress_callback`: Optional callback invoked periodically with sync progress - * - `completion_callback`: Optional callback invoked on completion - * - `user_data`: Optional user data pointer passed to all callbacks - * - * # Returns - * - * 0 on success, error code on failure - */ - -int32_t dash_spv_ffi_client_start_sync_with_progress(struct FFIDashSpvClient *client, - void (*progress_callback)(const struct FFIDetailedSyncProgress*, - void*), - void (*completion_callback)(bool, - const char*, - void*), - void *user_data) -; - -/** - * 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. - */ - int32_t dash_spv_ffi_client_stop(struct FFIDashSpvClient *client) ; - -/** - * Get the current sync progress snapshot. - * - * # Safety - * - `client` must be a valid, non-null pointer. - */ - struct FFISyncProgress *dash_spv_ffi_client_get_sync_progress(struct FFIDashSpvClient *client) ; - -/** - * Get current runtime statistics for the SPV client. - * - * # Safety - * - `client` must be a valid, non-null pointer. - */ - 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. - * - * # Safety - * - `client` must be a valid, non-null pointer. - */ - bool dash_spv_ffi_client_is_filter_sync_available(struct FFIDashSpvClient *client) ; - -/** - * Set event callbacks for the client. - * - * # Safety - * - `client` must be a valid, non-null pointer. - */ - -int32_t dash_spv_ffi_client_set_event_callbacks(struct FFIDashSpvClient *client, - struct FFIEventCallbacks callbacks) -; - -/** - * Destroy the client and free associated resources. - * - * # Safety - * - `client` must be either null or a pointer obtained from `dash_spv_ffi_client_new`. - */ - void dash_spv_ffi_client_destroy(struct FFIDashSpvClient *client) ; - -/** - * Destroy a `FFISyncProgress` object returned by this crate. - * - * # Safety - * - `progress` must be a pointer returned from this crate, or null. - */ - void dash_spv_ffi_sync_progress_destroy(struct FFISyncProgress *progress) ; - -/** - * Destroy an `FFISpvStats` object returned by this crate. - * - * # Safety - * - `stats` must be a pointer returned from this crate, or null. - */ - void dash_spv_ffi_spv_stats_destroy(struct FFISpvStats *stats) ; - -/** - * Request a rescan of the blockchain from a given height (not yet implemented). - * - * # Safety - * - `client` must be a valid, non-null pointer. - */ - -int32_t dash_spv_ffi_client_rescan_blockchain(struct FFIDashSpvClient *client, - uint32_t _from_height) -; - -/** - * Enable mempool tracking with a given strategy. - * - * # Safety - * - `client` must be a valid, non-null pointer. - */ - -int32_t dash_spv_ffi_client_enable_mempool_tracking(struct FFIDashSpvClient *client, - enum FFIMempoolStrategy strategy) -; - -/** - * Record that we attempted to send a transaction by its txid. - * - * # Safety - * - `client` and `txid` must be valid, non-null pointers. - */ - int32_t dash_spv_ffi_client_record_send(struct FFIDashSpvClient *client, const char *txid) ; - -/** - * Get the wallet manager from the SPV client - * - * Returns a pointer to an `FFIWalletManager` wrapper that clones the underlying - * `Arc>`. This allows direct interaction with the wallet - * manager without going back through the client for each call. - * - * # Safety - * - * The caller must ensure that: - * - The client pointer is valid - * - The returned pointer is released exactly once using - * `dash_spv_ffi_wallet_manager_free` - * - * # Returns - * - * A pointer to the wallet manager wrapper, or NULL if the client is not initialized. - */ - FFIWalletManager *dash_spv_ffi_client_get_wallet_manager(struct FFIDashSpvClient *client) ; - -/** - * Release a wallet manager obtained from `dash_spv_ffi_client_get_wallet_manager`. - * - * This simply forwards to `wallet_manager_free` in key-wallet-ffi so that - * lifetime management is consistent between direct key-wallet usage and the - * SPV client pathway. - * - * # Safety - * - `manager` must either be null or a pointer previously returned by - * `dash_spv_ffi_client_get_wallet_manager`. - */ - void dash_spv_ffi_wallet_manager_free(FFIWalletManager *manager) ; - - struct FFIClientConfig *dash_spv_ffi_config_new(FFINetwork network) ; - - struct FFIClientConfig *dash_spv_ffi_config_mainnet(void) ; - - struct FFIClientConfig *dash_spv_ffi_config_testnet(void) ; - -/** - * Sets the data directory for storing blockchain data - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - `path` must be a valid null-terminated C string - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_data_dir(struct FFIClientConfig *config, - const char *path) -; - -/** - * Sets the validation mode for the SPV client - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_validation_mode(struct FFIClientConfig *config, - enum DashSpvValidationMode mode) -; - -/** - * Sets the maximum number of peers to connect to - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_max_peers(struct FFIClientConfig *config, - uint32_t max_peers) -; - -/** - * Adds a peer address to the configuration - * - * Accepts either a full socket address (e.g., "192.168.1.1:9999" or "[::1]:19999") - * or an IP-only string (e.g., "127.0.0.1" or "2001:db8::1"). When an IP-only - * string is given, the default P2P port for the configured network is used. - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - `addr` must be a valid null-terminated C string containing a socket address or IP-only string - * - The caller must ensure both pointers remain valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_add_peer(struct FFIClientConfig *config, - const char *addr) -; - -/** - * Sets the user agent string to advertise in the P2P handshake - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - `user_agent` must be a valid null-terminated C string - * - The caller must ensure both pointers remain valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_user_agent(struct FFIClientConfig *config, - const char *user_agent) -; - -/** - * Sets whether to relay transactions (currently a no-op) - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_relay_transactions(struct FFIClientConfig *config, - bool _relay) -; - -/** - * Sets whether to load bloom filters - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_filter_load(struct FFIClientConfig *config, - bool load_filters) -; - -/** - * Restrict connections strictly to configured peers (disable DNS discovery and peer store) - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - */ - -int32_t dash_spv_ffi_config_set_restrict_to_configured_peers(struct FFIClientConfig *config, - bool restrict_peers) -; - -/** - * Enables or disables masternode synchronization - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_masternode_sync_enabled(struct FFIClientConfig *config, - bool enable) -; - -/** - * Gets the network type from the configuration - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig or null - * - If null, returns FFINetwork::Mainnet as default - */ - FFINetwork dash_spv_ffi_config_get_network(const struct FFIClientConfig *config) ; - -/** - * Gets the data directory path from the configuration - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig or null - * - If null or no data directory is set, returns an FFIString with null pointer - * - The returned FFIString must be freed by the caller using `dash_spv_ffi_string_destroy` - */ - struct FFIString dash_spv_ffi_config_get_data_dir(const struct FFIClientConfig *config) ; - -/** - * Destroys an FFIClientConfig and frees its memory - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet, or null - * - After calling this function, the config pointer becomes invalid and must not be used - * - This function should only be called once per config instance - */ - -void dash_spv_ffi_config_destroy(struct FFIClientConfig *config) -; - -/** - * Sets the number of Tokio worker threads for the FFI runtime (0 = auto) - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig - */ - int32_t dash_spv_ffi_config_set_worker_threads(struct FFIClientConfig *config, uint32_t threads) ; - -/** - * Enables or disables mempool tracking - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_mempool_tracking(struct FFIClientConfig *config, - bool enable) -; - -/** - * Sets the mempool synchronization strategy - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_mempool_strategy(struct FFIClientConfig *config, - enum FFIMempoolStrategy strategy) -; - -/** - * Sets the maximum number of mempool transactions to track - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_max_mempool_transactions(struct FFIClientConfig *config, - uint32_t max_transactions) -; - -/** - * Sets the mempool transaction timeout in seconds - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_mempool_timeout(struct FFIClientConfig *config, - uint64_t timeout_secs) -; - -/** - * Sets whether to fetch full mempool transaction data - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_fetch_mempool_transactions(struct FFIClientConfig *config, - bool fetch) -; - -/** - * Sets whether to persist mempool state to disk - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_persist_mempool(struct FFIClientConfig *config, - bool persist) -; - -/** - * Gets whether mempool tracking is enabled - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig or null - * - If null, returns false as default - */ - bool dash_spv_ffi_config_get_mempool_tracking(const struct FFIClientConfig *config) ; - -/** - * Gets the mempool synchronization strategy - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig or null - * - If null, returns FFIMempoolStrategy::Selective as default - */ - -enum FFIMempoolStrategy dash_spv_ffi_config_get_mempool_strategy(const struct FFIClientConfig *config) -; - -/** - * Sets the starting block height for synchronization - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_start_from_height(struct FFIClientConfig *config, - uint32_t height) -; - -/** - * Sets the wallet creation timestamp for synchronization optimization - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_wallet_creation_time(struct FFIClientConfig *config, - uint32_t timestamp) -; - - const char *dash_spv_ffi_get_last_error(void) ; - - void dash_spv_ffi_clear_error(void) ; - -/** - * Creates a CoreSDKHandle from an FFIDashSpvClient - * - * # Safety - * - * This function is unsafe because: - * - The caller must ensure the client pointer is valid - * - The returned handle must be properly released with ffi_dash_spv_release_core_handle - */ - struct CoreSDKHandle *ffi_dash_spv_get_core_handle(struct FFIDashSpvClient *client) ; - -/** - * Releases a CoreSDKHandle - * - * # Safety - * - * This function is unsafe because: - * - The caller must ensure the handle pointer is valid - * - The handle must not be used after this call - */ - void ffi_dash_spv_release_core_handle(struct CoreSDKHandle *handle) ; - -/** - * Gets a quorum public key from the Core chain - * - * # Safety - * - * This function is unsafe because: - * - The caller must ensure all pointers are valid - * - quorum_hash must point to a 32-byte array - * - out_pubkey must point to a buffer of at least out_pubkey_size bytes - * - out_pubkey_size must be at least 48 bytes - */ - -struct FFIResult ffi_dash_spv_get_quorum_public_key(struct FFIDashSpvClient *client, - uint32_t quorum_type, - const uint8_t *quorum_hash, - uint32_t core_chain_locked_height, - uint8_t *out_pubkey, - uintptr_t out_pubkey_size) -; - -/** - * Gets the platform activation height from the Core chain - * - * # Safety - * - * This function is unsafe because: - * - The caller must ensure all pointers are valid - * - out_height must point to a valid u32 - */ - -struct FFIResult ffi_dash_spv_get_platform_activation_height(struct FFIDashSpvClient *client, - uint32_t *out_height) -; - -/** - * # Safety - * - `s.ptr` must be a pointer previously returned by `FFIString::new` or compatible. - * - It must not be used after this call. - */ - void dash_spv_ffi_string_destroy(struct FFIString s) ; - -/** - * # Safety - * - `arr` must be either null or a valid pointer to an `FFIArray` previously constructed in Rust. - * - The memory referenced by `arr.data` must not be used after this call. - */ - void dash_spv_ffi_array_destroy(struct FFIArray *arr) ; - -/** - * Destroy an array of FFIString pointers (Vec<*mut FFIString>) and their contents. - * - * This function: - * - Iterates the array elements as pointers to FFIString and destroys each via dash_spv_ffi_string_destroy - * - Frees the underlying vector buffer stored in FFIArray - * - Does not free the FFIArray struct itself (safe for both stack- and heap-allocated structs) - * # Safety - * - `arr` must be either null or a valid pointer to an `FFIArray` whose elements are `*mut FFIString`. - * - Each element pointer must be valid or null; non-null entries are freed. - * - The memory referenced by `arr.data` must not be used after this call. - */ - -void dash_spv_ffi_string_array_destroy(struct FFIArray *arr) -; - -/** - * Destroys the raw transaction bytes allocated for an FFIUnconfirmedTransaction - * - * # Safety - * - * - `raw_tx` must be a valid pointer to memory allocated by the caller - * - `raw_tx_len` must be the correct length of the allocated memory - * - The pointer must not be used after this function is called - * - This function should only be called once per allocation - */ - void dash_spv_ffi_unconfirmed_transaction_destroy_raw_tx(uint8_t *raw_tx, uintptr_t raw_tx_len) ; - -/** - * Destroys the addresses array allocated for an FFIUnconfirmedTransaction - * - * # Safety - * - * - `addresses` must be a valid pointer to an array of FFIString objects - * - `addresses_len` must be the correct length of the array - * - Each FFIString in the array must be destroyed separately using `dash_spv_ffi_string_destroy` - * - The pointer must not be used after this function is called - * - This function should only be called once per allocation - */ - -void dash_spv_ffi_unconfirmed_transaction_destroy_addresses(struct FFIString *addresses, - uintptr_t addresses_len) -; - -/** - * Destroys an FFIUnconfirmedTransaction and all its associated resources - * - * # Safety - * - * - `tx` must be a valid pointer to an FFIUnconfirmedTransaction - * - All resources (raw_tx, addresses array, and individual FFIStrings) will be freed - * - The pointer must not be used after this function is called - * - This function should only be called once per FFIUnconfirmedTransaction - */ - void dash_spv_ffi_unconfirmed_transaction_destroy(struct FFIUnconfirmedTransaction *tx) ; - -/** - * Initialize logging for the SPV library. - * - * # Safety - * - `level` may be null or point to a valid, NUL-terminated C string. - * - If non-null, the pointer must remain valid for the duration of this call. - */ - int32_t dash_spv_ffi_init_logging(const char *level) ; - - const char *dash_spv_ffi_version(void) ; - - void dash_spv_ffi_enable_test_mode(void) ; - - -int32_t dash_spv_ffi_client_broadcast_transaction(struct FFIDashSpvClient *client, - const char *tx_hex) -; - -#ifdef __cplusplus -} // extern "C" -#endif // __cplusplus - -#ifdef __cplusplus -} // namespace dash_spv_ffi -#endif // __cplusplus - -#endif /* DASH_SPV_FFI_H */ diff --git a/dash-spv-ffi/include/dash_spv_ffi.h b/dash-spv-ffi/include/dash_spv_ffi.h deleted file mode 100644 index 05290f78d..000000000 --- a/dash-spv-ffi/include/dash_spv_ffi.h +++ /dev/null @@ -1,1004 +0,0 @@ -/* dash-spv-ffi C bindings - Auto-generated by cbindgen */ - -#ifndef DASH_SPV_FFI_H -#define DASH_SPV_FFI_H - -/* Generated with cbindgen:0.29.2 */ - -/* Warning: This file is auto-generated by cbindgen. Do not modify manually. */ - -#include -#include -#include -#include - -#ifdef __cplusplus -namespace dash_spv_ffi { -#endif // __cplusplus - -/** - * SyncState exposed by the FFI as FFISyncState. - */ -typedef enum FFISyncState { - WaitForEvents = 0, - WaitingForConnections = 1, - Syncing = 2, - Synced = 3, - Error = 4, -} FFISyncState; - -/** - * Identifies which sync manager generated an event. - */ -typedef enum FFIManagerId { - Headers = 0, - FilterHeaders = 1, - Filters = 2, - Blocks = 3, - Masternodes = 4, - ChainLocks = 5, - InstantSend = 6, -} FFIManagerId; - -typedef enum FFIMempoolStrategy { - FetchAll = 0, - BloomFilter = 1, -} FFIMempoolStrategy; - -typedef struct FFIDashSpvClient FFIDashSpvClient; - -typedef struct FFIClientConfig { - void *inner; - uint32_t worker_threads; - -} FFIClientConfig; - -/** - * Progress for block headers synchronization. - */ -typedef struct FFIBlockHeadersProgress { - enum FFISyncState state; - uint32_t tip_height; - uint32_t target_height; - uint32_t processed; - uint32_t buffered; - double percentage; - uint64_t last_activity; -} FFIBlockHeadersProgress; - -/** - * Progress for filter headers synchronization. - */ -typedef struct FFIFilterHeadersProgress { - enum FFISyncState state; - uint32_t current_height; - uint32_t target_height; - uint32_t block_header_tip_height; - uint32_t processed; - double percentage; - uint64_t last_activity; -} FFIFilterHeadersProgress; - -/** - * Progress for compact block filters synchronization. - */ -typedef struct FFIFiltersProgress { - enum FFISyncState state; - uint32_t committed_height; - uint32_t stored_height; - uint32_t target_height; - uint32_t filter_header_tip_height; - uint32_t downloaded; - uint32_t processed; - uint32_t matched; - double percentage; - uint64_t last_activity; -} FFIFiltersProgress; - -/** - * Progress for full block synchronization. - */ -typedef struct FFIBlocksProgress { - enum FFISyncState state; - uint32_t last_processed; - uint32_t requested; - uint32_t from_storage; - uint32_t downloaded; - uint32_t processed; - uint32_t relevant; - uint32_t transactions; - uint64_t last_activity; -} FFIBlocksProgress; - -/** - * Progress for masternode list synchronization. - */ -typedef struct FFIMasternodesProgress { - enum FFISyncState state; - uint32_t current_height; - uint32_t target_height; - uint32_t block_header_tip_height; - uint32_t diffs_processed; - uint64_t last_activity; -} FFIMasternodesProgress; - -/** - * Progress for ChainLock synchronization. - */ -typedef struct FFIChainLockProgress { - enum FFISyncState state; - uint32_t best_validated_height; - uint32_t valid; - uint32_t invalid; - uint64_t last_activity; -} FFIChainLockProgress; - -/** - * Progress for InstantSend synchronization. - */ -typedef struct FFIInstantSendProgress { - enum FFISyncState state; - uint32_t pending; - uint32_t valid; - uint32_t invalid; - uint64_t last_activity; -} FFIInstantSendProgress; - -/** - * Aggregate progress for all sync managers. - * Provides a complete view of the parallel sync system's state. - */ -typedef struct FFISyncProgress { - enum FFISyncState state; - double percentage; - bool is_synced; - /** - * Per-manager progress (null if manager not started). - */ - struct FFIBlockHeadersProgress *headers; - struct FFIFilterHeadersProgress *filter_headers; - struct FFIFiltersProgress *filters; - struct FFIBlocksProgress *blocks; - struct FFIMasternodesProgress *masternodes; - struct FFIChainLockProgress *chainlocks; - struct FFIInstantSendProgress *instantsend; -} FFISyncProgress; - -/** - * Opaque handle to the wallet manager owned by the SPV client. - * - * This is intentionally zero-sized so it can be used purely as an FFI handle - * while still allowing Rust to cast to the underlying key-wallet manager - * implementation when necessary. - */ -typedef struct FFIWalletManager { - uint8_t _private[0]; -} FFIWalletManager; - -/** - * Callback for SyncEvent::SyncStart - */ -typedef void (*OnSyncStartCallback)(enum FFIManagerId manager_id, void *user_data); - -/** - * Callback for SyncEvent::BlockHeadersStored - */ -typedef void (*OnBlockHeadersStoredCallback)(uint32_t tip_height, void *user_data); - -/** - * Callback for SyncEvent::BlockHeaderSyncComplete - */ -typedef void (*OnBlockHeaderSyncCompleteCallback)(uint32_t tip_height, void *user_data); - -/** - * Callback for SyncEvent::FilterHeadersStored - */ -typedef void (*OnFilterHeadersStoredCallback)(uint32_t start_height, - uint32_t end_height, - uint32_t tip_height, - void *user_data); - -/** - * Callback for SyncEvent::FilterHeadersSyncComplete - */ -typedef void (*OnFilterHeadersSyncCompleteCallback)(uint32_t tip_height, void *user_data); - -/** - * Callback for SyncEvent::FiltersStored - */ -typedef void (*OnFiltersStoredCallback)(uint32_t start_height, uint32_t end_height, void *user_data); - -/** - * Callback for SyncEvent::FiltersSyncComplete - */ -typedef void (*OnFiltersSyncCompleteCallback)(uint32_t tip_height, void *user_data); - -/** - * A block that needs to be downloaded (height + hash). - */ -typedef struct FFIBlockNeeded { - /** - * Block height - */ - uint32_t height; - /** - * Block hash (32 bytes) - */ - uint8_t hash[32]; -} FFIBlockNeeded; - -/** - * Callback for SyncEvent::BlocksNeeded - * - * The `blocks` pointer points to an array of `FFIBlockNeeded` structs. - * The pointer is borrowed and only valid for the duration of the callback. - * Callers must memcpy/duplicate any data they need to retain after the - * callback returns. - */ -typedef void (*OnBlocksNeededCallback)(const struct FFIBlockNeeded *blocks, - uint32_t count, - void *user_data); - -/** - * Callback for SyncEvent::BlockProcessed - * - * The `hash` pointer is borrowed and only valid for the duration of the - * callback. Callers must memcpy/duplicate it to retain the value after - * the callback returns. - */ -typedef void (*OnBlockProcessedCallback)(uint32_t height, - const uint8_t (*hash)[32], - uint32_t new_address_count, - void *user_data); - -/** - * Callback for SyncEvent::MasternodeStateUpdated - */ -typedef void (*OnMasternodeStateUpdatedCallback)(uint32_t height, void *user_data); - -/** - * Callback for SyncEvent::ChainLockReceived - * - * The `hash` and `signature` pointers are borrowed and only valid for the - * duration of the callback. Callers must memcpy/duplicate them to retain - * the values after the callback returns. - */ -typedef void (*OnChainLockReceivedCallback)(uint32_t height, - const uint8_t (*hash)[32], - const uint8_t (*signature)[96], - bool validated, - void *user_data); - -/** - * Callback for SyncEvent::InstantLockReceived - * - * The `txid` pointer is borrowed and only valid for the duration of the callback. - * The `instantlock_data` pointer points to the consensus-serialized InstantLock - * bytes and is only valid for the duration of the callback. - * Callers must memcpy/duplicate any data they need to retain. - */ -typedef void (*OnInstantLockReceivedCallback)(const uint8_t (*txid)[32], - const uint8_t *instantlock_data, - uintptr_t instantlock_len, - bool validated, - void *user_data); - -/** - * Callback for SyncEvent::ManagerError - * - * 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 (*OnManagerErrorCallback)(enum FFIManagerId manager_id, - const char *error, - void *user_data); - -/** - * Callback for SyncEvent::SyncComplete - */ -typedef void (*OnSyncCompleteCallback)(uint32_t header_tip, uint32_t cycle, void *user_data); - -/** - * Sync event callbacks - one callback per SyncEvent variant. - * - * Set only the callbacks you're interested in; unset callbacks will be ignored. - * - * All pointer parameters passed to callbacks (strings, hashes, arrays) are - * borrowed and only valid for the duration of the callback invocation. - * Callers must memcpy/duplicate any data they need to retain. - */ -typedef struct FFISyncEventCallbacks { - OnSyncStartCallback on_sync_start; - OnBlockHeadersStoredCallback on_block_headers_stored; - OnBlockHeaderSyncCompleteCallback on_block_header_sync_complete; - OnFilterHeadersStoredCallback on_filter_headers_stored; - OnFilterHeadersSyncCompleteCallback on_filter_headers_sync_complete; - OnFiltersStoredCallback on_filters_stored; - OnFiltersSyncCompleteCallback on_filters_sync_complete; - OnBlocksNeededCallback on_blocks_needed; - OnBlockProcessedCallback on_block_processed; - OnMasternodeStateUpdatedCallback on_masternode_state_updated; - OnChainLockReceivedCallback on_chainlock_received; - OnInstantLockReceivedCallback on_instantlock_received; - OnManagerErrorCallback on_manager_error; - OnSyncCompleteCallback on_sync_complete; - void *user_data; -} FFISyncEventCallbacks; - -/** - * Callback for NetworkEvent::PeerConnected - * - * The `address` 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 (*OnPeerConnectedCallback)(const char *address, void *user_data); - -/** - * Callback for NetworkEvent::PeerDisconnected - * - * The `address` 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 (*OnPeerDisconnectedCallback)(const char *address, void *user_data); - -/** - * Callback for NetworkEvent::PeersUpdated - */ -typedef void (*OnPeersUpdatedCallback)(uint32_t connected_count, - uint32_t best_height, - void *user_data); - -/** - * Network event callbacks - one callback per NetworkEvent variant. - * - * Set only the callbacks you're interested in; unset callbacks will be ignored. - * - * All pointer parameters passed to callbacks (strings, addresses) are - * borrowed and only valid for the duration of the callback invocation. - * Callers must copy any data they need to retain. - */ -typedef struct FFINetworkEventCallbacks { - OnPeerConnectedCallback on_peer_connected; - OnPeerDisconnectedCallback on_peer_disconnected; - OnPeersUpdatedCallback on_peers_updated; - void *user_data; -} FFINetworkEventCallbacks; - -/** - * Callback for WalletEvent::TransactionReceived - * - * The `wallet_id`, `addresses` string pointers and the `txid` hash pointer - * are borrowed and only valid for the duration of the callback. Callers must - * copy any data they need to retain after the callback returns. - */ -typedef void (*OnTransactionReceivedCallback)(const char *wallet_id, - uint32_t account_index, - const uint8_t (*txid)[32], - int64_t amount, - const char *addresses, - void *user_data); - -/** - * Callback for WalletEvent::BalanceUpdated - * - * The `wallet_id` 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 (*OnBalanceUpdatedCallback)(const char *wallet_id, - uint64_t spendable, - uint64_t unconfirmed, - uint64_t immature, - uint64_t locked, - void *user_data); - -/** - * Wallet event callbacks - one callback per WalletEvent variant. - * - * Set only the callbacks you're interested in; unset callbacks will be ignored. - * - * All pointer parameters passed to callbacks (wallet IDs, txids, addresses) - * are borrowed and only valid for the duration of the callback invocation. - * Callers must copy any data they need to retain. - */ -typedef struct FFIWalletEventCallbacks { - OnTransactionReceivedCallback on_transaction_received; - OnBalanceUpdatedCallback on_balance_updated; - void *user_data; -} FFIWalletEventCallbacks; - -/** - * Callback for sync progress updates. - * - * Called whenever the sync progress changes. The progress pointer is only - * valid for the duration of the callback. The caller must NOT free the - * progress pointer - it will be freed automatically after the callback returns. - */ -typedef void (*OnProgressUpdateCallback)(const struct FFISyncProgress *progress, void *user_data); - -/** - * Progress callback configuration. - */ -typedef struct FFIProgressCallback { - /** - * Callback function for progress updates. - */ - OnProgressUpdateCallback on_progress; - /** - * User data passed to the callback. - */ - 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 - */ -typedef struct FFIResult { - int32_t error_code; - const char *error_message; -} FFIResult; - -#ifdef __cplusplus -extern "C" { -#endif // __cplusplus - -/** - * Create a new SPV client and return an opaque pointer. - * - * # Safety - * - `config` must be a valid, non-null pointer for the duration of the call. - * - The returned pointer must be freed with `dash_spv_ffi_client_destroy`. - */ - struct FFIDashSpvClient *dash_spv_ffi_client_new(const struct FFIClientConfig *config) ; - -/** - * Update the running client's configuration. - * - * # Safety - * - `client` must be a valid pointer to an `FFIDashSpvClient`. - * - `config` must be a valid pointer to an `FFIClientConfig`. - * - The network in `config` must match the client's network; changing networks at runtime is not supported. - */ - -int32_t dash_spv_ffi_client_update_config(struct FFIDashSpvClient *client, - const struct FFIClientConfig *config) -; - -/** - * Stop the SPV client. - * - * # Safety - * - `client` must be a valid, non-null pointer to a created client. - */ - int32_t dash_spv_ffi_client_stop(struct FFIDashSpvClient *client) ; - -/** - * 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. - */ - int32_t dash_spv_ffi_client_run(struct FFIDashSpvClient *client) ; - -/** - * Get the current sync progress snapshot. - * - * # Safety - * - `client` must be a valid, non-null pointer. - */ - struct FFISyncProgress *dash_spv_ffi_client_get_sync_progress(struct FFIDashSpvClient *client) ; - -/** - * Get the current manager-based sync progress. - * - * Returns the new parallel sync system's progress with per-manager details. - * Use `dash_spv_ffi_sync_progress_destroy` to free the returned struct. - * - * # Safety - * - `client` must be a valid, non-null pointer. - */ - -struct FFISyncProgress *dash_spv_ffi_client_get_manager_sync_progress(struct FFIDashSpvClient *client) -; - -/** - * 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) ; - -/** - * Broadcasts a transaction to the Dash network via connected peers. - * - * # Safety - * - * - `client` must be a valid, non-null pointer to an initialized FFIDashSpvClient - * - `tx_bytes` must be a valid, non-null pointer to the transaction data - * - `length` must be the length of the transaction data in bytes - */ - -int32_t dash_spv_ffi_client_broadcast_transaction(struct FFIDashSpvClient *client, - const uint8_t *tx_bytes, - uintptr_t length) -; - -/** - * Destroy the client and free associated resources. - * - * # Safety - * - `client` must be either null or a pointer obtained from `dash_spv_ffi_client_new`. - */ - void dash_spv_ffi_client_destroy(struct FFIDashSpvClient *client) ; - -/** - * Get the wallet manager from the SPV client - * - * Returns a pointer to an `FFIWalletManager` wrapper that clones the underlying - * `Arc>`. This allows direct interaction with the wallet - * manager without going back through the client for each call. - * - * # Safety - * - * The caller must ensure that: - * - The client pointer is valid - * - The returned pointer is released exactly once using - * `dash_spv_ffi_wallet_manager_free` - * - * # Returns - * - * A pointer to the wallet manager wrapper, or NULL if the client is not initialized. - */ - struct FFIWalletManager *dash_spv_ffi_client_get_wallet_manager(struct FFIDashSpvClient *client) ; - -/** - * Release a wallet manager obtained from `dash_spv_ffi_client_get_wallet_manager`. - * - * This simply forwards to `wallet_manager_free` in key-wallet-ffi so that - * lifetime management is consistent between direct key-wallet usage and the - * SPV client pathway. - * - * # Safety - * - `manager` must either be null or a pointer previously returned by - * `dash_spv_ffi_client_get_wallet_manager`. - */ - void dash_spv_ffi_wallet_manager_free(struct FFIWalletManager *manager) ; - -/** - * 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. - */ - -int32_t dash_spv_ffi_client_set_sync_event_callbacks(struct FFIDashSpvClient *client, - struct FFISyncEventCallbacks callbacks) -; - -/** - * Clear sync event callbacks. - * - * # Safety - * - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - */ - int32_t dash_spv_ffi_client_clear_sync_event_callbacks(struct FFIDashSpvClient *client) ; - -/** - * 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. - */ - -int32_t dash_spv_ffi_client_set_network_event_callbacks(struct FFIDashSpvClient *client, - struct FFINetworkEventCallbacks callbacks) -; - -/** - * Clear network event callbacks. - * - * # Safety - * - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - */ - int32_t dash_spv_ffi_client_clear_network_event_callbacks(struct FFIDashSpvClient *client) ; - -/** - * 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. - */ - -int32_t dash_spv_ffi_client_set_wallet_event_callbacks(struct FFIDashSpvClient *client, - struct FFIWalletEventCallbacks callbacks) -; - -/** - * Clear wallet event callbacks. - * - * # Safety - * - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - */ - int32_t dash_spv_ffi_client_clear_wallet_event_callbacks(struct FFIDashSpvClient *client) ; - -/** - * 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. - */ - -int32_t dash_spv_ffi_client_set_progress_callback(struct FFIDashSpvClient *client, - struct FFIProgressCallback callback) -; - -/** - * Clear progress callback. - * - * # Safety - * - `client` must be a valid, non-null pointer to an `FFIDashSpvClient`. - */ - 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) ; - - struct FFIClientConfig *dash_spv_ffi_config_testnet(void) ; - -/** - * Sets the data directory for storing blockchain data - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - `path` must be a valid null-terminated C string - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_data_dir(struct FFIClientConfig *config, - const char *path) -; - -/** - * Adds a peer address to the configuration - * - * Accepts socket addresses with or without port. When no port is specified, - * the default P2P port for the configured network is used. - * - * Supported formats: - * - IP with port: `192.168.1.1:9999`, `[::1]:19999` - * - IP without port: `127.0.0.1`, `2001:db8::1` - * - Hostname with port: `node.example.com:9999` - * - Hostname without port: `node.example.com` - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - `addr` must be a valid null-terminated C string containing a socket address or IP-only string - * - The caller must ensure both pointers remain valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_add_peer(struct FFIClientConfig *config, - const char *addr) -; - -/** - * Sets the user agent string to advertise in the P2P handshake - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - `user_agent` must be a valid null-terminated C string - * - The caller must ensure both pointers remain valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_user_agent(struct FFIClientConfig *config, - const char *user_agent) -; - -/** - * Restrict connections strictly to configured peers (disable DNS discovery and peer store) - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - */ - -int32_t dash_spv_ffi_config_set_restrict_to_configured_peers(struct FFIClientConfig *config, - bool restrict_peers) -; - -/** - * Enables or disables masternode synchronization - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_masternode_sync_enabled(struct FFIClientConfig *config, - bool enable) -; - -/** - * Gets the network type from the configuration - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig or null - * - If null, returns FFINetwork::Mainnet as default - */ - FFINetwork dash_spv_ffi_config_get_network(const struct FFIClientConfig *config) ; - -/** - * Destroys an FFIClientConfig and frees its memory - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet, or null - * - After calling this function, the config pointer becomes invalid and must not be used - * - This function should only be called once per config instance - */ - -void dash_spv_ffi_config_destroy(struct FFIClientConfig *config) -; - -/** - * Enables or disables mempool tracking - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_mempool_tracking(struct FFIClientConfig *config, - bool enable) -; - -/** - * Sets the mempool synchronization strategy - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_mempool_strategy(struct FFIClientConfig *config, - enum FFIMempoolStrategy strategy) -; - -/** - * Sets whether to fetch full mempool transaction data - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_fetch_mempool_transactions(struct FFIClientConfig *config, - bool fetch) -; - -/** - * Sets whether to persist mempool state to disk - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_persist_mempool(struct FFIClientConfig *config, - bool persist) -; - -/** - * Sets the starting block height for synchronization - * - * # Safety - * - `config` must be a valid pointer to an FFIClientConfig created by dash_spv_ffi_config_new/mainnet/testnet - * - The caller must ensure the config pointer remains valid for the duration of this call - */ - -int32_t dash_spv_ffi_config_set_start_from_height(struct FFIClientConfig *config, - uint32_t height) -; - - const char *dash_spv_ffi_get_last_error(void) ; - -/** - * Gets a quorum public key from the Core chain - * - * # Safety - * - * This function is unsafe because: - * - The caller must ensure all pointers are valid - * - quorum_hash must point to a 32-byte array - * - out_pubkey must point to a buffer of at least out_pubkey_size bytes - * - out_pubkey_size must be at least 48 bytes - */ - -struct FFIResult ffi_dash_spv_get_quorum_public_key(struct FFIDashSpvClient *client, - uint32_t quorum_type, - const uint8_t *quorum_hash, - uint32_t core_chain_locked_height, - uint8_t *out_pubkey, - uintptr_t out_pubkey_size) -; - -/** - * Gets the platform activation height from the Core chain - * - * # Safety - * - * This function is unsafe because: - * - The caller must ensure all pointers are valid - * - out_height must point to a valid u32 - */ - -struct FFIResult ffi_dash_spv_get_platform_activation_height(struct FFIDashSpvClient *client, - uint32_t *out_height) -; - -/** - * Destroy an `FFIBlockHeadersProgress` object. - * - * # Safety - * - `progress` must be a pointer returned from this crate, or null. - */ - void dash_spv_ffi_block_headers_progress_destroy(struct FFIBlockHeadersProgress *progress) ; - -/** - * Destroy an `FFIFilterHeadersProgress` object. - * - * # Safety - * - `progress` must be a pointer returned from this crate, or null. - */ - void dash_spv_ffi_filter_headers_progress_destroy(struct FFIFilterHeadersProgress *progress) ; - -/** - * Destroy an `FFIFiltersProgress` object. - * - * # Safety - * - `progress` must be a pointer returned from this crate, or null. - */ - void dash_spv_ffi_filters_progress_destroy(struct FFIFiltersProgress *progress) ; - -/** - * Destroy an `FFIBlocksProgress` object. - * - * # Safety - * - `progress` must be a pointer returned from this crate, or null. - */ - void dash_spv_ffi_blocks_progress_destroy(struct FFIBlocksProgress *progress) ; - -/** - * Destroy an `FFIMasternodesProgress` object. - * - * # Safety - * - `progress` must be a pointer returned from this crate, or null. - */ - void dash_spv_ffi_masternode_progress_destroy(struct FFIMasternodesProgress *progress) ; - -/** - * Destroy an `FFIChainLockProgress` object. - * - * # Safety - * - `progress` must be a pointer returned from this crate, or null. - */ - void dash_spv_ffi_chainlock_progress_destroy(struct FFIChainLockProgress *progress) ; - -/** - * Destroy an `FFIInstantSendProgress` object. - * - * # Safety - * - `progress` must be a pointer returned from this crate, or null. - */ - void dash_spv_ffi_instantsend_progress_destroy(struct FFIInstantSendProgress *progress) ; - -/** - * Destroy an `FFISyncProgress` object and all its nested pointers. - * - * # Safety - * - `progress` must be a pointer returned from this crate, or null. - */ - void dash_spv_ffi_sync_progress_destroy(struct FFISyncProgress *progress) ; - -/** - * Initialize logging for the SPV library. - * - * # Arguments - * - `level`: Log level string (null uses RUST_LOG env var or defaults to INFO). - * Valid values: "error", "warn", "info", "debug", "trace" - * - `enable_console`: Whether to output logs to console (stderr) - * - `log_dir`: Directory for log files (null to disable file logging) - * - `max_files`: Maximum archived log files to retain (ignored if log_dir is null) - * - * # Safety - * - `level` and `log_dir` may be null or point to valid, NUL-terminated C strings. - */ - -int32_t dash_spv_ffi_init_logging(const char *level, - bool enable_console, - const char *log_dir, - uintptr_t max_files) -; - - const char *dash_spv_ffi_version(void) ; - -#ifdef __cplusplus -} // extern "C" -#endif // __cplusplus - -#ifdef __cplusplus -} // namespace dash_spv_ffi -#endif // __cplusplus - -#endif /* DASH_SPV_FFI_H */ diff --git a/key-wallet-ffi/Makefile b/key-wallet-ffi/Makefile index c756b8171..888759d8a 100644 --- a/key-wallet-ffi/Makefile +++ b/key-wallet-ffi/Makefile @@ -14,12 +14,6 @@ test: # Clean build artifacts clean: cargo clean - rm -f include/key_wallet_ffi.h - -# Generate C header -header: - cargo build --release - @echo "Generated header at include/key_wallet_ffi.h" # Update FFI documentation update-docs: @@ -32,7 +26,7 @@ check-docs: @bash scripts/check_ffi_docs.sh # Generate all documentation -docs: header update-docs +docs: update-docs @echo "All documentation generated" # Build for iOS @@ -40,7 +34,7 @@ ios: ./build-ios.sh # Full build with documentation -full: clean build header update-docs +full: clean build update-docs @echo "Full build complete with documentation" # Help @@ -49,7 +43,6 @@ help: @echo " make build - Build the library" @echo " make test - Run tests" @echo " make clean - Clean build artifacts" - @echo " make header - Generate C header" @echo " make update-docs - Update FFI API documentation" @echo " make check-docs - Check if FFI docs are up to date" @echo " make docs - Generate all documentation" diff --git a/key-wallet-ffi/build.rs b/key-wallet-ffi/build.rs index 5519a0d86..14970c647 100644 --- a/key-wallet-ffi/build.rs +++ b/key-wallet-ffi/build.rs @@ -35,7 +35,7 @@ fn main() { println!("cargo:warning=Generated C header at {:?}", output_path); } Err(e) => { - println!("cargo:warning=Failed to generate C header: {}", e); + panic!("Failed to generate C header via cbindgen: {}", e); } } } diff --git a/key-wallet-ffi/include/key_wallet_ffi.h b/key-wallet-ffi/include/key_wallet_ffi.h deleted file mode 100644 index ccedce946..000000000 --- a/key-wallet-ffi/include/key_wallet_ffi.h +++ /dev/null @@ -1,4528 +0,0 @@ -/** - * Key Wallet FFI - C Header File - * - * This header provides C-compatible function declarations for the key-wallet - * Rust library FFI bindings. - * - * AUTO-GENERATED FILE - DO NOT EDIT - * Generated using cbindgen - */ - -#ifndef KEY_WALLET_FFI_H -#define KEY_WALLET_FFI_H - -/* Generated with cbindgen:0.29.2 */ - -/* Warning: This file is auto-generated by cbindgen. Do not modify manually. */ - -#include -#include -#include -#include -#include -#include -#include -#include - -/* - Account type enumeration matching all key_wallet AccountType variants - - This enum provides a complete FFI representation of all account types - supported by the key_wallet library: - - - Standard accounts: BIP44 and BIP32 variants for regular transactions - - CoinJoin: Privacy-enhanced transactions - - Identity accounts: Registration, top-up, and invitation funding - - Provider accounts: Various masternode provider key types (voting, owner, operator, platform) - */ -typedef enum { - /* - Standard BIP44 account (m/44'/coin_type'/account'/x/x) - */ - STANDARD_BIP44 = 0, - /* - Standard BIP32 account (m/account'/x/x) - */ - STANDARD_BIP32 = 1, - /* - CoinJoin account for private transactions - */ - COIN_JOIN = 2, - /* - Identity registration funding - */ - IDENTITY_REGISTRATION = 3, - /* - Identity top-up funding (requires registration_index) - */ - IDENTITY_TOP_UP = 4, - /* - Identity top-up funding not bound to a specific identity - */ - IDENTITY_TOP_UP_NOT_BOUND_TO_IDENTITY = 5, - /* - Identity invitation funding - */ - IDENTITY_INVITATION = 6, - /* - Provider voting keys (DIP-3) - Path: m/9'/5'/3'/1'/\[key_index\] - */ - PROVIDER_VOTING_KEYS = 7, - /* - Provider owner keys (DIP-3) - Path: m/9'/5'/3'/2'/\[key_index\] - */ - PROVIDER_OWNER_KEYS = 8, - /* - Provider operator keys (DIP-3) - Path: m/9'/5'/3'/3'/\[key_index\] - */ - PROVIDER_OPERATOR_KEYS = 9, - /* - Provider platform P2P keys (DIP-3, ED25519) - Path: m/9'/5'/3'/4'/\[key_index\] - */ - PROVIDER_PLATFORM_KEYS = 10, - /* - DashPay incoming funds account using 256-bit derivation - */ - DASHPAY_RECEIVING_FUNDS = 11, - /* - DashPay external (watch-only) account using 256-bit derivation - */ - DASHPAY_EXTERNAL_ACCOUNT = 12, - /* - Platform Payment address (DIP-17) - Path: m/9'/5'/17'/account'/key_class'/index - */ - PLATFORM_PAYMENT = 13, - /* - Asset lock address top-up funding (subfeature 4) - */ - ASSET_LOCK_ADDRESS_TOP_UP = 14, - /* - Asset lock shielded address top-up funding (subfeature 5) - */ - ASSET_LOCK_SHIELDED_ADDRESS_TOP_UP = 15, -} FFIAccountType; - -/* - FFI Network type (single network) - */ -typedef enum { - MAINNET = 0, - TESTNET = 1, - REGTEST = 2, - DEVNET = 3, -} FFINetwork; - -/* - FFI Error code - */ -typedef enum { - SUCCESS = 0, - INVALID_INPUT = 1, - ALLOCATION_FAILED = 2, - INVALID_MNEMONIC = 3, - INVALID_DERIVATION_PATH = 4, - INVALID_NETWORK = 5, - INVALID_ADDRESS = 6, - INVALID_TRANSACTION = 7, - WALLET_ERROR = 8, - SERIALIZATION_ERROR = 9, - NOT_FOUND = 10, - INVALID_STATE = 11, - INTERNAL_ERROR = 12, -} FFIErrorCode; - -/* - Address pool type - */ -typedef enum { - /* - External (receive) addresses - */ - EXTERNAL = 0, - /* - Internal (change) addresses - */ - INTERNAL = 1, - /* - Single pool (for non-standard accounts) - */ - SINGLE = 2, -} FFIAddressPoolType; - -/* - Language enumeration for mnemonic generation - - This enum must be kept in sync with key_wallet::mnemonic::Language. - When adding new languages to the key_wallet crate, remember to update - this FFI enum and both From implementations below. - */ -typedef enum { - ENGLISH = 0, - CHINESE_SIMPLIFIED = 1, - CHINESE_TRADITIONAL = 2, - CZECH = 3, - FRENCH = 4, - ITALIAN = 5, - JAPANESE = 6, - KOREAN = 7, - PORTUGUESE = 8, - SPANISH = 9, -} FFILanguage; - -/* - FFI-compatible transaction context - */ -typedef enum { - /* - Transaction is in the mempool (unconfirmed) - */ - MEMPOOL = 0, - /* - Transaction is in the mempool with an InstantSend lock - */ - INSTANT_SEND = 1, - /* - Transaction is in a block at the given height - */ - IN_BLOCK = 2, - /* - Transaction is in a chain-locked block at the given height - */ - IN_CHAIN_LOCKED_BLOCK = 3, -} FFITransactionContext; - -/* - FFI Account Creation Option Type - */ -typedef enum { - /* - Create default accounts (BIP44 account 0, CoinJoin account 0, and special accounts) - */ - DEFAULT = 0, - /* - Create all specified accounts plus all special purpose accounts - */ - ALL_ACCOUNTS = 1, - /* - Create only BIP44 accounts (no CoinJoin or special accounts) - */ - BIP44_ACCOUNTS_ONLY = 2, - /* - Create specific accounts with full control - */ - SPECIFIC_ACCOUNTS = 3, - /* - Create no accounts at all - */ - NO_ACCOUNTS = 4, -} FFIAccountCreationOptionType; - -/* - Opaque account handle - */ -typedef struct FFIAccount FFIAccount; - -/* - Opaque handle to an account collection - */ -typedef struct FFIAccountCollection FFIAccountCollection; - -/* - FFI wrapper for an AddressPool from a ManagedAccount - - This is a lightweight wrapper that holds a reference to an AddressPool - from within a ManagedAccount. It allows querying addresses and pool information. - */ -typedef struct FFIAddressPool FFIAddressPool; - -/* - Opaque BLS account handle - */ -typedef struct FFIBLSAccount FFIBLSAccount; - -/* - Opaque EdDSA account handle - */ -typedef struct FFIEdDSAAccount FFIEdDSAAccount; - -/* - Extended private key structure - */ -typedef struct FFIExtendedPrivKey FFIExtendedPrivKey; - -/* - Opaque type for an extended private key - */ -typedef struct FFIExtendedPrivateKey FFIExtendedPrivateKey; - -/* - Extended public key structure - */ -typedef struct FFIExtendedPubKey FFIExtendedPubKey; - -/* - Opaque type for an extended public key - */ -typedef struct FFIExtendedPublicKey FFIExtendedPublicKey; - -/* - Opaque managed account handle that wraps ManagedAccount - */ -typedef struct FFIManagedCoreAccount FFIManagedCoreAccount; - -/* - Opaque handle to a managed account collection - */ -typedef struct FFIManagedCoreAccountCollection FFIManagedCoreAccountCollection; - -/* - Opaque managed platform account handle that wraps ManagedPlatformAccount - - This is different from FFIManagedCoreAccount because ManagedPlatformAccount - has a different structure optimized for Platform Payment accounts (DIP-17): - - Simple u64 credit balance instead of WalletCoreBalance - - Per-address balances tracked directly - - No transactions or UTXOs (Platform handles these) - */ -typedef struct FFIManagedPlatformAccount FFIManagedPlatformAccount; - -/* - Opaque type for a private key (SecretKey) - */ -typedef struct FFIPrivateKey FFIPrivateKey; - -/* - Opaque type for a public key - */ -typedef struct FFIPublicKey FFIPublicKey; - -/* - Opaque handle for a transaction - */ -typedef struct FFITransaction FFITransaction; - -/* - Opaque wallet handle - */ -typedef struct FFIWallet FFIWallet; - -/* - FFI wrapper for WalletManager - - This struct holds a cloned Arc reference to the WalletManager, - allowing FFI code to interact with it directly without going through - the SPV client. - */ -typedef struct FFIWalletManager FFIWalletManager; - -/* - FFI Result type for Account operations - */ -typedef struct { - /* - The account handle if successful, NULL if error - */ - FFIAccount *account; - /* - Error code (0 = success) - */ - int32_t error_code; - /* - Error message (NULL if success, must be freed by caller if not NULL) - */ - char *error_message; -} FFIAccountResult; - -/* - FFI Error structure - */ -typedef struct { - FFIErrorCode code; - char *message; -} FFIError; - -/* - C-compatible summary of all accounts in a collection - - This struct provides Swift with structured data about all accounts - that exist in the collection, allowing programmatic access to account - indices and presence information. - */ -typedef struct { - /* - Array of BIP44 account indices - */ - unsigned int *bip44_indices; - /* - Number of BIP44 accounts - */ - size_t bip44_count; - /* - Array of BIP32 account indices - */ - unsigned int *bip32_indices; - /* - Number of BIP32 accounts - */ - size_t bip32_count; - /* - Array of CoinJoin account indices - */ - unsigned int *coinjoin_indices; - /* - Number of CoinJoin accounts - */ - size_t coinjoin_count; - /* - Array of identity top-up registration indices - */ - unsigned int *identity_topup_indices; - /* - Number of identity top-up accounts - */ - size_t identity_topup_count; - /* - Whether identity registration account exists - */ - bool has_identity_registration; - /* - Whether identity invitation account exists - */ - bool has_identity_invitation; - /* - Whether identity top-up not bound account exists - */ - bool has_identity_topup_not_bound; - /* - Whether provider voting keys account exists - */ - bool has_provider_voting_keys; - /* - Whether provider owner keys account exists - */ - bool has_provider_owner_keys; - /* - Whether provider operator keys account exists - */ - bool has_provider_operator_keys; - /* - Whether provider platform keys account exists - */ - bool has_provider_platform_keys; -} FFIAccountCollectionSummary; - -/* - FFI wrapper for ManagedWalletInfo (single canonical type) - */ -typedef struct { - void *inner; -} FFIManagedWalletInfo; - -/* - Address pool info - */ -typedef struct { - /* - Pool type - */ - FFIAddressPoolType pool_type; - /* - Number of generated addresses - */ - unsigned int generated_count; - /* - Number of used addresses - */ - unsigned int used_count; - /* - Current gap (unused addresses at the end) - */ - unsigned int current_gap; - /* - Gap limit setting - */ - unsigned int gap_limit; - /* - Highest used index (-1 if none used) - */ - int32_t highest_used_index; -} FFIAddressPoolInfo; - -/* - FFI-compatible version of AddressInfo - */ -typedef struct { - /* - Address as string - */ - char *address; - /* - Script pubkey bytes - */ - uint8_t *script_pubkey; - /* - Length of script pubkey - */ - size_t script_pubkey_len; - /* - Public key bytes (nullable) - */ - uint8_t *public_key; - /* - Length of public key - */ - size_t public_key_len; - /* - Derivation index - */ - uint32_t index; - /* - Derivation path as string - */ - char *path; - /* - Whether address has been used - */ - bool used; - /* - When generated (timestamp) - */ - uint64_t generated_at; - /* - When first used (0 if never) - */ - uint64_t used_at; - /* - Transaction count - */ - uint32_t tx_count; - /* - Total received - */ - uint64_t total_received; - /* - Total sent - */ - uint64_t total_sent; - /* - Current balance - */ - uint64_t balance; - /* - Custom label (nullable) - */ - char *label; -} FFIAddressInfo; - -/* - FFI Result type for ManagedAccount operations - */ -typedef struct { - /* - The managed account handle if successful, NULL if error - */ - FFIManagedCoreAccount *account; - /* - Error code (0 = success) - */ - int32_t error_code; - /* - Error message (NULL if success, must be freed by caller if not NULL) - */ - char *error_message; -} FFIManagedCoreAccountResult; - -/* - FFI Balance type for representing wallet balances - */ -typedef struct { - /* - Confirmed balance in duffs - */ - uint64_t confirmed; - /* - Unconfirmed balance in duffs - */ - uint64_t unconfirmed; - /* - Immature balance in duffs (e.g., mining rewards not yet mature) - */ - uint64_t immature; - /* - Locked balance in duffs (e.g., CoinJoin reserves) - */ - uint64_t locked; - /* - Total balance in duffs - */ - uint64_t total; -} FFIBalance; - -/* - FFI-compatible transaction record - */ -typedef struct { - /* - Transaction ID (32 bytes) - */ - uint8_t txid[32]; - /* - Net amount for this account (positive = received, negative = sent) - */ - int64_t net_amount; - /* - Block height if confirmed, 0 if unconfirmed - */ - uint32_t height; - /* - Block hash if confirmed (32 bytes), all zeros if unconfirmed - */ - uint8_t block_hash[32]; - /* - Unix timestamp - */ - uint64_t timestamp; - /* - Fee if known, 0 if unknown - */ - uint64_t fee; - /* - Whether this is our transaction - */ - bool is_ours; -} FFITransactionRecord; - -/* - FFI Result type for ManagedPlatformAccount operations - */ -typedef struct { - /* - The managed platform account handle if successful, NULL if error - */ - FFIManagedPlatformAccount *account; - /* - Error code (0 = success) - */ - int32_t error_code; - /* - Error message (NULL if success, must be freed by caller if not NULL) - */ - char *error_message; -} FFIManagedPlatformAccountResult; - -/* - C-compatible platform payment account key - */ -typedef struct { - /* - Account index (hardened) - */ - unsigned int account; - /* - Key class (hardened) - */ - unsigned int key_class; -} FFIPlatformPaymentAccountKey; - -/* - C-compatible summary of all accounts in a managed collection - - This struct provides Swift with structured data about all accounts - that exist in the managed collection, allowing programmatic access to account - indices and presence information. - */ -typedef struct { - /* - Array of BIP44 account indices - */ - unsigned int *bip44_indices; - /* - Number of BIP44 accounts - */ - size_t bip44_count; - /* - Array of BIP32 account indices - */ - unsigned int *bip32_indices; - /* - Number of BIP32 accounts - */ - size_t bip32_count; - /* - Array of CoinJoin account indices - */ - unsigned int *coinjoin_indices; - /* - Number of CoinJoin accounts - */ - size_t coinjoin_count; - /* - Array of identity top-up registration indices - */ - unsigned int *identity_topup_indices; - /* - Number of identity top-up accounts - */ - size_t identity_topup_count; - /* - Whether identity registration account exists - */ - bool has_identity_registration; - /* - Whether identity invitation account exists - */ - bool has_identity_invitation; - /* - Whether identity top-up not bound account exists - */ - bool has_identity_topup_not_bound; - /* - Whether provider voting keys account exists - */ - bool has_provider_voting_keys; - /* - Whether provider owner keys account exists - */ - bool has_provider_owner_keys; - /* - Whether provider operator keys account exists - */ - bool has_provider_operator_keys; - /* - Whether provider platform keys account exists - */ - bool has_provider_platform_keys; - /* - Array of Platform Payment account keys (account, key_class pairs) - */ - FFIPlatformPaymentAccountKey *platform_payment_keys; - /* - Number of Platform Payment accounts - */ - size_t platform_payment_count; -} FFIManagedCoreAccountCollectionSummary; - -/* - Transaction output for building (legacy structure) - */ -typedef struct { - const char *address; - uint64_t amount; -} FFITxOutput; - -/* - Transaction check result - */ -typedef struct { - /* - Whether the transaction belongs to the wallet - */ - bool is_relevant; - /* - Total amount received - */ - uint64_t total_received; - /* - Total amount sent - */ - uint64_t total_sent; - /* - Number of affected accounts - */ - uint32_t affected_accounts_count; -} FFITransactionCheckResult; - -/* - FFI-compatible transaction input - */ -typedef struct { - /* - Transaction ID (32 bytes) - */ - uint8_t txid[32]; - /* - Output index - */ - uint32_t vout; - /* - Script signature length - */ - uint32_t script_sig_len; - /* - Script signature data pointer - */ - const uint8_t *script_sig; - /* - Sequence number - */ - uint32_t sequence; -} FFITxIn; - -/* - FFI-compatible transaction output - */ -typedef struct { - /* - Amount in duffs - */ - uint64_t amount; - /* - Script pubkey length - */ - uint32_t script_pubkey_len; - /* - Script pubkey data pointer - */ - const uint8_t *script_pubkey; -} FFITxOut; - -/* - UTXO structure for FFI - */ -typedef struct { - uint8_t txid[32]; - uint32_t vout; - uint64_t amount; - char *address; - uint8_t *script_pubkey; - size_t script_len; - uint32_t height; - uint32_t confirmations; -} FFIUTXO; - -/* - FFI specification for a PlatformPayment account to create - - PlatformPayment accounts (DIP-17) use the derivation path: - `m/9'/coin_type'/17'/account'/key_class'/index` - */ -typedef struct { - /* - Account index (hardened) - the account' level in the derivation path - */ - uint32_t account; - /* - Key class (hardened) - defaults to 0', 1' is reserved for change-like segregation - */ - uint32_t key_class; -} FFIPlatformPaymentAccountSpec; - -/* - FFI structure for wallet account creation options - This single struct represents all possible account creation configurations - */ -typedef struct { - /* - The type of account creation option - */ - FFIAccountCreationOptionType option_type; - /* - Array of BIP44 account indices to create - */ - const uint32_t *bip44_indices; - size_t bip44_count; - /* - Array of BIP32 account indices to create - */ - const uint32_t *bip32_indices; - size_t bip32_count; - /* - Array of CoinJoin account indices to create - */ - const uint32_t *coinjoin_indices; - size_t coinjoin_count; - /* - Array of identity top-up registration indices to create - */ - const uint32_t *topup_indices; - size_t topup_count; - /* - Array of PlatformPayment account specs to create - */ - const FFIPlatformPaymentAccountSpec *platform_payment_specs; - size_t platform_payment_count; - /* - For SpecificAccounts: Additional special account types to create - (e.g., IdentityRegistration, ProviderKeys, etc.) - This is an array of FFIAccountType values - */ - const FFIAccountType *special_account_types; - size_t special_account_types_count; -} FFIWalletAccountCreationOptions; - -/* - FFI-compatible transaction context details - */ -typedef struct { - /* - The context type - */ - FFITransactionContext context_type; - /* - Block height (0 for mempool) - */ - unsigned int height; - /* - Block hash (32 bytes, null for mempool or if unknown) - */ - const uint8_t *block_hash; - /* - Timestamp (0 if unknown) - */ - unsigned int timestamp; -} FFITransactionContextDetails; - -#ifdef __cplusplus -extern "C" { -#endif // __cplusplus - -/* - Initialize the library - */ - bool key_wallet_ffi_initialize(void) ; - -/* - Get library version - - Returns a static string that should NOT be freed by the caller - */ - const char *key_wallet_ffi_version(void) ; - -/* - Get an account handle for a specific account type - Returns a result containing either the account handle or an error - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet instance - - The caller must ensure the wallet pointer remains valid for the duration of this call - */ - -FFIAccountResult wallet_get_account(const FFIWallet *wallet, - unsigned int account_index, - FFIAccountType account_type) -; - -/* - Get an IdentityTopUp account handle with a specific registration index - This is used for top-up accounts that are bound to a specific identity - Returns a result containing either the account handle or an error - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet instance - - The caller must ensure the wallet pointer remains valid for the duration of this call - */ - -FFIAccountResult wallet_get_top_up_account_with_registration_index(const FFIWallet *wallet, - unsigned int registration_index) -; - -/* - Free an account handle - - # Safety - - - `account` must be a valid pointer to an FFIAccount that was allocated by this library - - The pointer must not be used after calling this function - - This function must only be called once per allocation - */ - void account_free(FFIAccount *account) ; - -/* - Free a BLS account handle - - # Safety - - - `account` must be a valid pointer to an FFIBLSAccount - - The pointer must not be used after calling this function - - This function must only be called once per allocation - */ - void bls_account_free(FFIBLSAccount *account) ; - -/* - Free an EdDSA account handle - - # Safety - - - `account` must be a valid pointer to an FFIEdDSAAccount - - The pointer must not be used after calling this function - - This function must only be called once per allocation - */ - void eddsa_account_free(FFIEdDSAAccount *account) ; - -/* - Free an account result's error message (if any) - Note: This does NOT free the account handle itself - use account_free for that - - # Safety - - - `result` must be a valid pointer to an FFIAccountResult - - The error_message field must be either null or a valid CString allocated by this library - - The caller must ensure the result pointer remains valid for the duration of this call - */ - void account_result_free_error(FFIAccountResult *result) ; - -/* - Get the extended public key of an account as a string - - # Safety - - - `account` must be a valid pointer to an FFIAccount instance - - The returned string must be freed by the caller using `string_free` - - Returns NULL if the account is null - */ - char *account_get_extended_public_key_as_string(const FFIAccount *account) ; - -/* - Get the network of an account - - # Safety - - - `account` must be a valid pointer to an FFIAccount instance - - Returns `FFINetwork::Mainnet` if the account is null - */ - FFINetwork account_get_network(const FFIAccount *account) ; - -/* - Get the parent wallet ID of an account - - # Safety - - - `account` must be a valid pointer to an FFIAccount instance - - Returns a pointer to the 32-byte wallet ID, or NULL if not set or account is null - - The returned pointer is valid only as long as the account exists - - The caller should copy the data if needed for longer use - */ - const uint8_t *account_get_parent_wallet_id(const FFIAccount *account) ; - -/* - Get the account type of an account - - # Safety - - - `account` must be a valid pointer to an FFIAccount instance - - `out_index` must be a valid pointer to a c_uint where the index will be stored - - Returns FFIAccountType::StandardBIP44 with index 0 if the account is null - */ - FFIAccountType account_get_account_type(const FFIAccount *account, unsigned int *out_index) ; - -/* - Check if an account is watch-only - - # Safety - - - `account` must be a valid pointer to an FFIAccount instance - - Returns false if the account is null - */ - bool account_get_is_watch_only(const FFIAccount *account) ; - -/* - Get the extended public key of a BLS account as a string - - # Safety - - - `account` must be a valid pointer to an FFIBLSAccount instance - - The returned string must be freed by the caller using `string_free` - - Returns NULL if the account is null - */ - char *bls_account_get_extended_public_key_as_string(const FFIBLSAccount *account) ; - -/* - Get the network of a BLS account - - # Safety - - - `account` must be a valid pointer to an FFIBLSAccount instance - - Returns `FFINetwork::Mainnet` if the account is null - */ - FFINetwork bls_account_get_network(const FFIBLSAccount *account) ; - -/* - Get the parent wallet ID of a BLS account - - # Safety - - - `account` must be a valid pointer to an FFIBLSAccount instance - - Returns a pointer to the 32-byte wallet ID, or NULL if not set or account is null - - The returned pointer is valid only as long as the account exists - - The caller should copy the data if needed for longer use - */ - const uint8_t *bls_account_get_parent_wallet_id(const FFIBLSAccount *account) ; - -/* - Get the account type of a BLS account - - # Safety - - - `account` must be a valid pointer to an FFIBLSAccount instance - - `out_index` must be a valid pointer to a c_uint where the index will be stored - - Returns FFIAccountType::StandardBIP44 with index 0 if the account is null - */ - -FFIAccountType bls_account_get_account_type(const FFIBLSAccount *account, - unsigned int *out_index) -; - -/* - Check if a BLS account is watch-only - - # Safety - - - `account` must be a valid pointer to an FFIBLSAccount instance - - Returns false if the account is null - */ - bool bls_account_get_is_watch_only(const FFIBLSAccount *account) ; - -/* - Get the extended public key of an EdDSA account as a string - - # Safety - - - `account` must be a valid pointer to an FFIEdDSAAccount instance - - The returned string must be freed by the caller using `string_free` - - Returns NULL if the account is null - */ - char *eddsa_account_get_extended_public_key_as_string(const FFIEdDSAAccount *account) ; - -/* - Get the network of an EdDSA account - - # Safety - - - `account` must be a valid pointer to an FFIEdDSAAccount instance - - Returns `FFINetwork::Mainnet` if the account is null - */ - FFINetwork eddsa_account_get_network(const FFIEdDSAAccount *account) ; - -/* - Get the parent wallet ID of an EdDSA account - - # Safety - - - `account` must be a valid pointer to an FFIEdDSAAccount instance - - Returns a pointer to the 32-byte wallet ID, or NULL if not set or account is null - - The returned pointer is valid only as long as the account exists - - The caller should copy the data if needed for longer use - */ - const uint8_t *eddsa_account_get_parent_wallet_id(const FFIEdDSAAccount *account) ; - -/* - Get the account type of an EdDSA account - - # Safety - - - `account` must be a valid pointer to an FFIEdDSAAccount instance - - `out_index` must be a valid pointer to a c_uint where the index will be stored - - Returns FFIAccountType::StandardBIP44 with index 0 if the account is null - */ - -FFIAccountType eddsa_account_get_account_type(const FFIEdDSAAccount *account, - unsigned int *out_index) -; - -/* - Check if an EdDSA account is watch-only - - # Safety - - - `account` must be a valid pointer to an FFIEdDSAAccount instance - - Returns false if the account is null - */ - bool eddsa_account_get_is_watch_only(const FFIEdDSAAccount *account) ; - -/* - Get number of accounts - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet instance - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure both pointers remain valid for the duration of this call - */ - unsigned int wallet_get_account_count(const FFIWallet *wallet, FFIError *error) ; - -/* - Get account collection for a specific network from wallet - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet instance - - `error` must be a valid pointer to an FFIError structure or null - - The returned pointer must be freed with `account_collection_free` when no longer needed - */ - FFIAccountCollection *wallet_get_account_collection(const FFIWallet *wallet, FFIError *error) ; - -/* - Free an account collection handle - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection created by this library - - `collection` must not be used after calling this function - */ - void account_collection_free(FFIAccountCollection *collection) ; - -/* - Get a BIP44 account by index from the collection - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - The returned pointer must be freed with `account_free` when no longer needed - */ - -FFIAccount *account_collection_get_bip44_account(const FFIAccountCollection *collection, - unsigned int index) -; - -/* - Get all BIP44 account indices - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - `out_indices` must be a valid pointer to store the indices array - - `out_count` must be a valid pointer to store the count - - The returned array must be freed with `free_u32_array` when no longer needed - */ - -bool account_collection_get_bip44_indices(const FFIAccountCollection *collection, - unsigned int **out_indices, - size_t *out_count) -; - -/* - Get a BIP32 account by index from the collection - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - The returned pointer must be freed with `account_free` when no longer needed - */ - -FFIAccount *account_collection_get_bip32_account(const FFIAccountCollection *collection, - unsigned int index) -; - -/* - Get all BIP32 account indices - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - `out_indices` must be a valid pointer to store the indices array - - `out_count` must be a valid pointer to store the count - - The returned array must be freed with `free_u32_array` when no longer needed - */ - -bool account_collection_get_bip32_indices(const FFIAccountCollection *collection, - unsigned int **out_indices, - size_t *out_count) -; - -/* - Get a CoinJoin account by index from the collection - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - The returned pointer must be freed with `account_free` when no longer needed - */ - -FFIAccount *account_collection_get_coinjoin_account(const FFIAccountCollection *collection, - unsigned int index) -; - -/* - Get all CoinJoin account indices - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - `out_indices` must be a valid pointer to store the indices array - - `out_count` must be a valid pointer to store the count - - The returned array must be freed with `free_u32_array` when no longer needed - */ - -bool account_collection_get_coinjoin_indices(const FFIAccountCollection *collection, - unsigned int **out_indices, - size_t *out_count) -; - -/* - Get the identity registration account if it exists - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - The returned pointer must be freed with `account_free` when no longer needed - */ - FFIAccount *account_collection_get_identity_registration(const FFIAccountCollection *collection) ; - -/* - Check if identity registration account exists - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - */ - bool account_collection_has_identity_registration(const FFIAccountCollection *collection) ; - -/* - Get an identity topup account by registration index - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - The returned pointer must be freed with `account_free` when no longer needed - */ - -FFIAccount *account_collection_get_identity_topup(const FFIAccountCollection *collection, - unsigned int registration_index) -; - -/* - Get all identity topup registration indices - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - `out_indices` must be a valid pointer to store the indices array - - `out_count` must be a valid pointer to store the count - - The returned array must be freed with `free_u32_array` when no longer needed - */ - -bool account_collection_get_identity_topup_indices(const FFIAccountCollection *collection, - unsigned int **out_indices, - size_t *out_count) -; - -/* - Get the identity topup not bound account if it exists - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - The returned pointer must be freed with `account_free` when no longer needed - */ - -FFIAccount *account_collection_get_identity_topup_not_bound(const FFIAccountCollection *collection) -; - -/* - Check if identity topup not bound account exists - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - */ - bool account_collection_has_identity_topup_not_bound(const FFIAccountCollection *collection) ; - -/* - Get the identity invitation account if it exists - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - The returned pointer must be freed with `account_free` when no longer needed - */ - FFIAccount *account_collection_get_identity_invitation(const FFIAccountCollection *collection) ; - -/* - Check if identity invitation account exists - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - */ - bool account_collection_has_identity_invitation(const FFIAccountCollection *collection) ; - -/* - Get the provider voting keys account if it exists - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - The returned pointer must be freed with `account_free` when no longer needed - */ - FFIAccount *account_collection_get_provider_voting_keys(const FFIAccountCollection *collection) ; - -/* - Check if provider voting keys account exists - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - */ - bool account_collection_has_provider_voting_keys(const FFIAccountCollection *collection) ; - -/* - Get the provider owner keys account if it exists - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - The returned pointer must be freed with `account_free` when no longer needed - */ - FFIAccount *account_collection_get_provider_owner_keys(const FFIAccountCollection *collection) ; - -/* - Check if provider owner keys account exists - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - */ - bool account_collection_has_provider_owner_keys(const FFIAccountCollection *collection) ; - -/* - Get the provider operator keys account if it exists - Note: Returns null if the `bls` feature is not enabled - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - The returned pointer must be freed with `bls_account_free` when no longer needed (when BLS is enabled) - */ - -void *account_collection_get_provider_operator_keys(const FFIAccountCollection *collection) -; - -/* - Check if provider operator keys account exists - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - */ - bool account_collection_has_provider_operator_keys(const FFIAccountCollection *collection) ; - -/* - Get the provider platform keys account if it exists - Note: Returns null if the `eddsa` feature is not enabled - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - The returned pointer must be freed with `eddsa_account_free` when no longer needed (when EdDSA is enabled) - */ - -void *account_collection_get_provider_platform_keys(const FFIAccountCollection *collection) -; - -/* - Check if provider platform keys account exists - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - */ - bool account_collection_has_provider_platform_keys(const FFIAccountCollection *collection) ; - -/* - Free a u32 array allocated by this library - - # Safety - - - `array` must be a valid pointer to an array allocated by this library - - `array` must not be used after calling this function - */ - void free_u32_array(unsigned int *array, size_t count) ; - -/* - Get the total number of accounts in the collection - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - */ - unsigned int account_collection_count(const FFIAccountCollection *collection) ; - -/* - Get a human-readable summary of all accounts in the collection - - Returns a formatted string showing all account types and their indices. - The format is designed to be clear and readable for end users. - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - The returned string must be freed with `string_free` when no longer needed - - Returns null if the collection pointer is null - */ - char *account_collection_summary(const FFIAccountCollection *collection) ; - -/* - Get structured account collection summary data - - Returns a struct containing arrays of indices for each account type and boolean - flags for special accounts. This provides Swift with programmatic access to - account information. - - # Safety - - - `collection` must be a valid pointer to an FFIAccountCollection - - The returned pointer must be freed with `account_collection_summary_free` when no longer needed - - Returns null if the collection pointer is null - */ - -FFIAccountCollectionSummary *account_collection_summary_data(const FFIAccountCollection *collection) -; - -/* - Free an account collection summary and all its allocated memory - - # Safety - - - `summary` must be a valid pointer to an FFIAccountCollectionSummary created by `account_collection_summary_data` - - `summary` must not be used after calling this function - */ - -void account_collection_summary_free(FFIAccountCollectionSummary *summary) -; - -/* - Derive an extended private key from an account at a given index, using the provided master xpriv. - - Returns an opaque FFIExtendedPrivateKey pointer that must be freed with `extended_private_key_free`. - - Notes: - - This is chain-agnostic. For accounts with internal/external chains, this returns an error. - - For hardened-only account types (e.g., EdDSA), a hardened index is used. - - # Safety - - `account` and `master_xpriv` must be valid, non-null pointers allocated by this library. - - `error` must be a valid pointer to an FFIError or null. - - The caller must free the returned pointer with `extended_private_key_free`. - */ - -FFIExtendedPrivateKey *account_derive_extended_private_key_at(const FFIAccount *account, - const FFIExtendedPrivateKey *master_xpriv, - unsigned int index, - FFIError *error) -; - -/* - Derive a BLS private key from a raw seed buffer at the given index. - - Returns a newly allocated hex string of the 32-byte private key. The caller must free - it with `string_free`. - - Notes: - - Uses the account's network for master key creation. - - Chain-agnostic; may return an error for accounts with internal/external chains. - - # Safety - - `account` must be a valid, non-null pointer to an `FFIBLSAccount` (only when `bls` feature is enabled). - - `seed` must point to a readable buffer of length `seed_len` (1..=64 bytes expected). - - `error` must be a valid pointer to an FFIError or null. - - Returned string must be freed with `string_free`. - */ - -char *bls_account_derive_private_key_from_seed(const FFIBLSAccount *account, - const uint8_t *seed, - size_t seed_len, - unsigned int index, - FFIError *error) -; - -/* - Derive a BLS private key from a mnemonic + optional passphrase at the given index. - - Returns a newly allocated hex string of the 32-byte private key. The caller must free - it with `string_free`. - - Notes: - - Uses the English wordlist for parsing the mnemonic. - - Chain-agnostic; may return an error for accounts with internal/external chains. - - # Safety - - `account` must be a valid, non-null pointer to an `FFIBLSAccount` (only when `bls` feature is enabled). - - `mnemonic` must be a valid, null-terminated UTF-8 C string. - - `passphrase` may be null; if not null, must be a valid UTF-8 C string. - - `error` must be a valid pointer to an FFIError or null. - - Returned string must be freed with `string_free`. - */ - -char *bls_account_derive_private_key_from_mnemonic(const FFIBLSAccount *account, - const char *mnemonic, - const char *passphrase, - unsigned int index, - FFIError *error) -; - -/* - Derive an EdDSA (ed25519) private key from a raw seed buffer at the given index. - - Returns a newly allocated hex string of the 32-byte private key. The caller must free - it with `string_free`. - - Notes: - - EdDSA only supports hardened derivation; the index will be used accordingly. - - Chain-agnostic; EdDSA accounts typically do not have internal/external split. - - # Safety - - `account` must be a valid, non-null pointer to an `FFIEdDSAAccount` (only when `eddsa` feature is enabled). - - `seed` must point to a readable buffer of length `seed_len` (1..=64 bytes expected). - - `error` must be a valid pointer to an FFIError or null. - - Returned string must be freed with `string_free`. - */ - -char *eddsa_account_derive_private_key_from_seed(const FFIEdDSAAccount *account, - const uint8_t *seed, - size_t seed_len, - unsigned int index, - FFIError *error) -; - -/* - Derive an EdDSA (ed25519) private key from a mnemonic + optional passphrase at the given index. - - Returns a newly allocated hex string of the 32-byte private key. The caller must free - it with `string_free`. - - Notes: - - Uses the English wordlist for parsing the mnemonic. - - # Safety - - `account` must be a valid, non-null pointer to an `FFIEdDSAAccount` (only when `eddsa` feature is enabled). - - `mnemonic` must be a valid, null-terminated UTF-8 C string. - - `passphrase` may be null; if not null, must be a valid UTF-8 C string. - - `error` must be a valid pointer to an FFIError or null. - - Returned string must be freed with `string_free`. - */ - -char *eddsa_account_derive_private_key_from_mnemonic(const FFIEdDSAAccount *account, - const char *mnemonic, - const char *passphrase, - unsigned int index, - FFIError *error) -; - -/* - Derive a private key (secp256k1) from an account at a given chain/index, using the provided master xpriv. - Returns an opaque FFIPrivateKey pointer that must be freed with `private_key_free`. - - # Safety - - `account` and `master_xpriv` must be valid pointers allocated by this library - - `error` must be a valid pointer to an FFIError or null - */ - -FFIPrivateKey *account_derive_private_key_at(const FFIAccount *account, - const FFIExtendedPrivateKey *master_xpriv, - unsigned int index, - FFIError *error) -; - -/* - Derive a private key from an account at a given chain/index and return as WIF string. - Caller must free the returned string with `string_free`. - - # Safety - - `account` and `master_xpriv` must be valid pointers allocated by this library - - `error` must be a valid pointer to an FFIError or null - */ - -char *account_derive_private_key_as_wif_at(const FFIAccount *account, - const FFIExtendedPrivateKey *master_xpriv, - unsigned int index, - FFIError *error) -; - -/* - Derive an extended private key from a raw seed buffer at the given index. - Returns an opaque FFIExtendedPrivateKey pointer that must be freed with `extended_private_key_free`. - - # Safety - - `account` must be a valid pointer to an FFIAccount - - `seed` must point to a valid buffer of length `seed_len` - - `error` must be a valid pointer to an FFIError or null - */ - -FFIExtendedPrivateKey *account_derive_extended_private_key_from_seed(const FFIAccount *account, - const uint8_t *seed, - size_t seed_len, - unsigned int index, - FFIError *error) -; - -/* - Derive a private key from a raw seed buffer at the given index. - Returns an opaque FFIPrivateKey pointer that must be freed with `private_key_free`. - - # Safety - - `account` must be a valid pointer to an FFIAccount - - `seed` must point to a valid buffer of length `seed_len` - - `error` must be a valid pointer to an FFIError or null - */ - -FFIPrivateKey *account_derive_private_key_from_seed(const FFIAccount *account, - const uint8_t *seed, - size_t seed_len, - unsigned int index, - FFIError *error) -; - -/* - Derive an extended private key from a mnemonic + optional passphrase at the given index. - Returns an opaque FFIExtendedPrivateKey pointer that must be freed with `extended_private_key_free`. - - # Safety - - `account` must be a valid pointer to an FFIAccount - - `mnemonic` must be a valid, null-terminated C string - - `passphrase` may be null; if not null, must be a valid C string - - `error` must be a valid pointer to an FFIError or null - */ - -FFIExtendedPrivateKey *account_derive_extended_private_key_from_mnemonic(const FFIAccount *account, - const char *mnemonic, - const char *passphrase, - unsigned int index, - FFIError *error) -; - -/* - Derive a private key from a mnemonic + optional passphrase at the given index. - Returns an opaque FFIPrivateKey pointer that must be freed with `private_key_free`. - - # Safety - - `account` must be a valid pointer to an FFIAccount - - `mnemonic` must be a valid, null-terminated C string - - `passphrase` may be null; if not null, must be a valid C string - - `error` must be a valid pointer to an FFIError or null - */ - -FFIPrivateKey *account_derive_private_key_from_mnemonic(const FFIAccount *account, - const char *mnemonic, - const char *passphrase, - unsigned int index, - FFIError *error) -; - -/* - Free address string - - # Safety - - - `address` must be a valid pointer created by address functions or null - - After calling this function, the pointer becomes invalid - */ - void address_free(char *address) ; - -/* - Free address array - - # Safety - - - `addresses` must be a valid pointer to an array of address strings or null - - Each address in the array must be a valid C string pointer - - `count` must be the correct number of addresses in the array - - After calling this function, all pointers become invalid - */ - void address_array_free(char **addresses, size_t count) ; - -/* - Validate an address - - # Safety - - - `address` must be a valid null-terminated C string - - `error` must be a valid pointer to an FFIError - */ - bool address_validate(const char *address, FFINetwork network, FFIError *error) ; - -/* - Get address type - - Returns: - - 0: P2PKH address - - 1: P2SH address - - 2: Other address type - - u8::MAX (255): Error occurred - - # Safety - - - `address` must be a valid null-terminated C string - - `error` must be a valid pointer to an FFIError - */ - unsigned char address_get_type(const char *address, FFINetwork network, FFIError *error) ; - -/* - Free an address pool handle - - # Safety - - - `pool` must be a valid pointer to an FFIAddressPool that was allocated by this library - - The pointer must not be used after calling this function - - This function must only be called once per allocation - */ - void address_pool_free(FFIAddressPool *pool) ; - -/* - Get address pool information for an account - - # Safety - - - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - - `info_out` must be a valid pointer to store the pool info - - `error` must be a valid pointer to an FFIError or null - */ - -bool managed_wallet_get_address_pool_info(const FFIManagedWalletInfo *managed_wallet, - FFIAccountType account_type, - unsigned int account_index, - FFIAddressPoolType pool_type, - FFIAddressPoolInfo *info_out, - FFIError *error) -; - -/* - Set the gap limit for an address pool - - The gap limit determines how many unused addresses to maintain at the end - of the pool. This is important for wallet recovery and address discovery. - - # Safety - - - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - - `error` must be a valid pointer to an FFIError or null - */ - -bool managed_wallet_set_gap_limit(FFIManagedWalletInfo *managed_wallet, - FFIAccountType account_type, - unsigned int account_index, - FFIAddressPoolType pool_type, - unsigned int gap_limit, - FFIError *error) -; - -/* - Generate addresses up to a specific index in a pool - - This ensures that addresses up to and including the specified index exist - in the pool. This is useful for wallet recovery or when specific indices - are needed. - - # Safety - - - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - - `wallet` must be a valid pointer to an FFIWallet (for key derivation) - - `error` must be a valid pointer to an FFIError or null - */ - -bool managed_wallet_generate_addresses_to_index(FFIManagedWalletInfo *managed_wallet, - const FFIWallet *wallet, - FFIAccountType account_type, - unsigned int account_index, - FFIAddressPoolType pool_type, - unsigned int target_index, - FFIError *error) -; - -/* - Mark an address as used in the pool - - This updates the pool's tracking of which addresses have been used, - which is important for gap limit management and wallet recovery. - - # Safety - - - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - - `address` must be a valid C string - - `error` must be a valid pointer to an FFIError or null - */ - -bool managed_wallet_mark_address_used(FFIManagedWalletInfo *managed_wallet, - const char *address, - FFIError *error) -; - -/* - Get a single address info at a specific index from the pool - - Returns detailed information about the address at the given index, or NULL - if the index is out of bounds or not generated yet. - - # Safety - - - `pool` must be a valid pointer to an FFIAddressPool - - `error` must be a valid pointer to an FFIError or null - - The returned FFIAddressInfo must be freed using `address_info_free` - */ - -FFIAddressInfo *address_pool_get_address_at_index(const FFIAddressPool *pool, - uint32_t index, - FFIError *error) -; - -/* - Get a range of addresses from the pool - - Returns an array of FFIAddressInfo structures for addresses in the range [start_index, end_index). - The count_out parameter will be set to the actual number of addresses returned. - - Note: This function only reads existing addresses from the pool. It does not generate new addresses. - Use managed_wallet_generate_addresses_to_index if you need to generate addresses first. - - # Safety - - - `pool` must be a valid pointer to an FFIAddressPool - - `count_out` must be a valid pointer to store the count - - `error` must be a valid pointer to an FFIError or null - - The returned array must be freed using `address_info_array_free` - */ - -FFIAddressInfo **address_pool_get_addresses_in_range(const FFIAddressPool *pool, - uint32_t start_index, - uint32_t end_index, - size_t *count_out, - FFIError *error) -; - -/* - Free a single FFIAddressInfo structure - - # Safety - - - `info` must be a valid pointer to an FFIAddressInfo allocated by this library or null - - The pointer must not be used after calling this function - */ - void address_info_free(FFIAddressInfo *info) ; - -/* - Free an array of FFIAddressInfo structures - - # Safety - - - `infos` must be a valid pointer to an array of FFIAddressInfo pointers allocated by this library or null - - `count` must be the exact number of elements in the array - - The pointers must not be used after calling this function - */ - -void address_info_array_free(FFIAddressInfo **infos, - size_t count) -; - -/* - Create a new master extended private key from seed - - # Safety - - - `seed` must be a valid pointer to a byte array of `seed_len` length - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure the seed pointer remains valid for the duration of this call - */ - -FFIExtendedPrivKey *derivation_new_master_key(const uint8_t *seed, - size_t seed_len, - FFINetwork network, - FFIError *error) -; - -/* - Derive a BIP44 account path (m/44'/5'/account') - */ - -bool derivation_bip44_account_path(FFINetwork network, - unsigned int account_index, - char *path_out, - size_t path_max_len, - FFIError *error) -; - -/* - Derive a BIP44 payment path (m/44'/5'/account'/change/index) - */ - -bool derivation_bip44_payment_path(FFINetwork network, - unsigned int account_index, - bool is_change, - unsigned int address_index, - char *path_out, - size_t path_max_len, - FFIError *error) -; - -/* - Derive CoinJoin path (m/9'/5'/4'/account') - */ - -bool derivation_coinjoin_path(FFINetwork network, - unsigned int account_index, - char *path_out, - size_t path_max_len, - FFIError *error) -; - -/* - Derive identity registration path (m/9'/5'/5'/1'/index') - */ - -bool derivation_identity_registration_path(FFINetwork network, - unsigned int identity_index, - char *path_out, - size_t path_max_len, - FFIError *error) -; - -/* - Derive identity top-up path (m/9'/5'/5'/2'/identity_index'/top_up_index') - */ - -bool derivation_identity_topup_path(FFINetwork network, - unsigned int identity_index, - unsigned int topup_index, - char *path_out, - size_t path_max_len, - FFIError *error) -; - -/* - Derive identity authentication path (m/9'/5'/5'/0'/identity_index'/key_index') - */ - -bool derivation_identity_authentication_path(FFINetwork network, - unsigned int identity_index, - unsigned int key_index, - char *path_out, - size_t path_max_len, - FFIError *error) -; - -/* - Derive private key for a specific path from seed - - # Safety - - - `seed` must be a valid pointer to a byte array of `seed_len` length - - `path` must be a valid pointer to a null-terminated C string - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - -FFIExtendedPrivKey *derivation_derive_private_key_from_seed(const uint8_t *seed, - size_t seed_len, - const char *path, - FFINetwork network, - FFIError *error) -; - -/* - Derive public key from extended private key - - # Safety - - - `xpriv` must be a valid pointer to an FFIExtendedPrivKey - - `error` must be a valid pointer to an FFIError - - The returned pointer must be freed with `extended_public_key_free` - */ - FFIExtendedPubKey *derivation_xpriv_to_xpub(const FFIExtendedPrivKey *xpriv, FFIError *error) ; - -/* - Get extended private key as string - - # Safety - - - `xpriv` must be a valid pointer to an FFIExtendedPrivKey - - `error` must be a valid pointer to an FFIError - - The returned string must be freed with `string_free` - */ - char *derivation_xpriv_to_string(const FFIExtendedPrivKey *xpriv, FFIError *error) ; - -/* - Get extended public key as string - - # Safety - - - `xpub` must be a valid pointer to an FFIExtendedPubKey - - `error` must be a valid pointer to an FFIError - - The returned string must be freed with `string_free` - */ - char *derivation_xpub_to_string(const FFIExtendedPubKey *xpub, FFIError *error) ; - -/* - Get fingerprint from extended public key (4 bytes) - - # Safety - - - `xpub` must be a valid pointer to an FFIExtendedPubKey - - `fingerprint_out` must be a valid pointer to a buffer of at least 4 bytes - - `error` must be a valid pointer to an FFIError - */ - -bool derivation_xpub_fingerprint(const FFIExtendedPubKey *xpub, - uint8_t *fingerprint_out, - FFIError *error) -; - -/* - Free extended private key - - # Safety - - - `xpriv` must be a valid pointer to an FFIExtendedPrivKey that was allocated by this library - - The pointer must not be used after calling this function - - This function must only be called once per allocation - */ - void derivation_xpriv_free(FFIExtendedPrivKey *xpriv) ; - -/* - Free extended public key - - # Safety - - - `xpub` must be a valid pointer to an FFIExtendedPubKey that was allocated by this library - - The pointer must not be used after calling this function - - This function must only be called once per allocation - */ - void derivation_xpub_free(FFIExtendedPubKey *xpub) ; - -/* - Free derivation path string - - # Safety - - - `s` must be a valid pointer to a C string that was allocated by this library - - The pointer must not be used after calling this function - - This function must only be called once per allocation - */ - void derivation_string_free(char *s) ; - -/* - Derive an address from a private key - - # Safety - - `private_key` must be a valid pointer to 32 bytes - - `network` is the network for the address - - # Returns - - Pointer to C string with address (caller must free) - - NULL on error - */ - char *key_wallet_derive_address_from_key(const uint8_t *private_key, FFINetwork network) ; - -/* - Derive an address from a seed at a specific derivation path - - # Safety - - `seed` must be a valid pointer to 64 bytes - - `network` is the network for the address - - `path` must be a valid null-terminated C string (e.g., "m/44'/5'/0'/0/0") - - # Returns - - Pointer to C string with address (caller must free) - - NULL on error - */ - -char *key_wallet_derive_address_from_seed(const uint8_t *seed, - FFINetwork network, - const char *path) -; - -/* - Derive a private key from a seed at a specific derivation path - - # Safety - - `seed` must be a valid pointer to 64 bytes - - `path` must be a valid null-terminated C string (e.g., "m/44'/5'/0'/0/0") - - `key_out` must be a valid pointer to a buffer of at least 32 bytes - - # Returns - - 0 on success - - -1 on error - */ - -int32_t key_wallet_derive_private_key_from_seed(const uint8_t *seed, - const char *path, - uint8_t *key_out) -; - -/* - Free an error message - - # Safety - - - `message` must be a valid pointer to a C string that was allocated by this library - - The pointer must not be used after calling this function - - This function must only be called once per allocation - */ - void error_message_free(char *message) ; - -/* - Get extended private key for account - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet - - `error` must be a valid pointer to an FFIError - - The returned string must be freed with `string_free` - */ - -char *wallet_get_account_xpriv(const FFIWallet *wallet, - unsigned int account_index, - FFIError *error) -; - -/* - Get extended public key for account - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet - - `error` must be a valid pointer to an FFIError - - The returned string must be freed with `string_free` - */ - -char *wallet_get_account_xpub(const FFIWallet *wallet, - unsigned int account_index, - FFIError *error) -; - -/* - Derive private key at a specific path - Returns an opaque FFIPrivateKey pointer that must be freed with private_key_free - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet - - `derivation_path` must be a valid null-terminated C string - - `error` must be a valid pointer to an FFIError - - The returned pointer must be freed with `private_key_free` - */ - -FFIPrivateKey *wallet_derive_private_key(const FFIWallet *wallet, - const char *derivation_path, - FFIError *error) -; - -/* - Derive extended private key at a specific path - Returns an opaque FFIExtendedPrivateKey pointer that must be freed with extended_private_key_free - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet - - `derivation_path` must be a valid null-terminated C string - - `error` must be a valid pointer to an FFIError - - The returned pointer must be freed with `extended_private_key_free` - */ - -FFIExtendedPrivateKey *wallet_derive_extended_private_key(const FFIWallet *wallet, - const char *derivation_path, - FFIError *error) -; - -/* - Derive private key at a specific path and return as WIF string - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet - - `derivation_path` must be a valid null-terminated C string - - `error` must be a valid pointer to an FFIError - - The returned string must be freed with `string_free` - */ - -char *wallet_derive_private_key_as_wif(const FFIWallet *wallet, - const char *derivation_path, - FFIError *error) -; - -/* - Free a private key - - # Safety - - - `key` must be a valid pointer created by private key functions or null - - After calling this function, the pointer becomes invalid - */ - void private_key_free(FFIPrivateKey *key) ; - -/* - Free an extended private key - - # Safety - - - `key` must be a valid pointer created by extended private key functions or null - - After calling this function, the pointer becomes invalid - */ - void extended_private_key_free(FFIExtendedPrivateKey *key) ; - -/* - Get extended private key as string (xprv format) - - Returns the extended private key in base58 format (xprv... for mainnet, tprv... for testnet) - - # Safety - - - `key` must be a valid pointer to an FFIExtendedPrivateKey - - `network` is ignored; the network is encoded in the extended key - - `error` must be a valid pointer to an FFIError - - The returned string must be freed with `string_free` - */ - -char *extended_private_key_to_string(const FFIExtendedPrivateKey *key, - FFINetwork network, - FFIError *error) -; - -/* - Get the private key from an extended private key - - Extracts the non-extended private key from an extended private key. - - # Safety - - - `extended_key` must be a valid pointer to an FFIExtendedPrivateKey - - `error` must be a valid pointer to an FFIError - - The returned FFIPrivateKey must be freed with `private_key_free` - */ - -FFIPrivateKey *extended_private_key_get_private_key(const FFIExtendedPrivateKey *extended_key, - FFIError *error) -; - -/* - Get private key as WIF string from FFIPrivateKey - - # Safety - - - `key` must be a valid pointer to an FFIPrivateKey - - `error` must be a valid pointer to an FFIError - - The returned string must be freed with `string_free` - */ - char *private_key_to_wif(const FFIPrivateKey *key, FFINetwork network, FFIError *error) ; - -/* - Derive public key at a specific path - Returns an opaque FFIPublicKey pointer that must be freed with public_key_free - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet - - `derivation_path` must be a valid null-terminated C string - - `error` must be a valid pointer to an FFIError - - The returned pointer must be freed with `public_key_free` - */ - -FFIPublicKey *wallet_derive_public_key(const FFIWallet *wallet, - const char *derivation_path, - FFIError *error) -; - -/* - Derive extended public key at a specific path - Returns an opaque FFIExtendedPublicKey pointer that must be freed with extended_public_key_free - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet - - `derivation_path` must be a valid null-terminated C string - - `error` must be a valid pointer to an FFIError - - The returned pointer must be freed with `extended_public_key_free` - */ - -FFIExtendedPublicKey *wallet_derive_extended_public_key(const FFIWallet *wallet, - const char *derivation_path, - FFIError *error) -; - -/* - Derive public key at a specific path and return as hex string - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet - - `derivation_path` must be a valid null-terminated C string - - `error` must be a valid pointer to an FFIError - - The returned string must be freed with `string_free` - */ - -char *wallet_derive_public_key_as_hex(const FFIWallet *wallet, - const char *derivation_path, - FFIError *error) -; - -/* - Free a public key - - # Safety - - - `key` must be a valid pointer created by public key functions or null - - After calling this function, the pointer becomes invalid - */ - void public_key_free(FFIPublicKey *key) ; - -/* - Free an extended public key - - # Safety - - - `key` must be a valid pointer created by extended public key functions or null - - After calling this function, the pointer becomes invalid - */ - void extended_public_key_free(FFIExtendedPublicKey *key) ; - -/* - Get extended public key as string (xpub format) - - Returns the extended public key in base58 format (xpub... for mainnet, tpub... for testnet) - - # Safety - - - `key` must be a valid pointer to an FFIExtendedPublicKey - - `network` is ignored; the network is encoded in the extended key - - `error` must be a valid pointer to an FFIError - - The returned string must be freed with `string_free` - */ - -char *extended_public_key_to_string(const FFIExtendedPublicKey *key, - FFINetwork network, - FFIError *error) -; - -/* - Get the public key from an extended public key - - Extracts the non-extended public key from an extended public key. - - # Safety - - - `extended_key` must be a valid pointer to an FFIExtendedPublicKey - - `error` must be a valid pointer to an FFIError - - The returned FFIPublicKey must be freed with `public_key_free` - */ - -FFIPublicKey *extended_public_key_get_public_key(const FFIExtendedPublicKey *extended_key, - FFIError *error) -; - -/* - Get public key as hex string from FFIPublicKey - - # Safety - - - `key` must be a valid pointer to an FFIPublicKey - - `error` must be a valid pointer to an FFIError - - The returned string must be freed with `string_free` - */ - char *public_key_to_hex(const FFIPublicKey *key, FFIError *error) ; - -/* - Convert derivation path string to indices - - # Safety - - - `path` must be a valid null-terminated C string or null - - `indices_out` must be a valid pointer to store the indices array pointer - - `hardened_out` must be a valid pointer to store the hardened flags array pointer - - `count_out` must be a valid pointer to store the count - - `error` must be a valid pointer to an FFIError - - The returned arrays must be freed with `derivation_path_free` - */ - -bool derivation_path_parse(const char *path, - uint32_t **indices_out, - bool **hardened_out, - size_t *count_out, - FFIError *error) -; - -/* - Free derivation path arrays - Note: This function expects the count to properly free the slices - - # Safety - - - `indices` must be a valid pointer created by `derivation_path_parse` or null - - `hardened` must be a valid pointer created by `derivation_path_parse` or null - - `count` must match the count from `derivation_path_parse` - - After calling this function, the pointers become invalid - */ - void derivation_path_free(uint32_t *indices, bool *hardened, size_t count) ; - -/* - Get a managed account from a managed wallet - - This function gets a ManagedAccount from the wallet manager's managed wallet info, - returning a managed account handle that wraps the ManagedAccount. - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `wallet_id` must be a valid pointer to a 32-byte wallet ID - - The caller must ensure all pointers remain valid for the duration of this call - - The returned account must be freed with `managed_core_account_free` when no longer needed - */ - -FFIManagedCoreAccountResult managed_wallet_get_account(const FFIWalletManager *manager, - const uint8_t *wallet_id, - unsigned int account_index, - FFIAccountType account_type) -; - -/* - Get a managed IdentityTopUp account with a specific registration index - - This is used for top-up accounts that are bound to a specific identity. - Returns a managed account handle that wraps the ManagedAccount. - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `wallet_id` must be a valid pointer to a 32-byte wallet ID - - The caller must ensure all pointers remain valid for the duration of this call - - The returned account must be freed with `managed_core_account_free` when no longer needed - */ - -FFIManagedCoreAccountResult managed_wallet_get_top_up_account_with_registration_index(const FFIWalletManager *manager, - const uint8_t *wallet_id, - unsigned int registration_index) -; - -/* - Get a managed DashPay receiving funds account by composite key - - # Safety - - `manager`, `wallet_id` must be valid - - `user_identity_id` and `friend_identity_id` must each point to 32 bytes - */ - -FFIManagedCoreAccountResult managed_wallet_get_dashpay_receiving_account(const FFIWalletManager *manager, - const uint8_t *wallet_id, - unsigned int account_index, - const uint8_t *user_identity_id, - const uint8_t *friend_identity_id) -; - -/* - Get a managed DashPay external account by composite key - - # Safety - - Pointers must be valid - */ - -FFIManagedCoreAccountResult managed_wallet_get_dashpay_external_account(const FFIWalletManager *manager, - const uint8_t *wallet_id, - unsigned int account_index, - const uint8_t *user_identity_id, - const uint8_t *friend_identity_id) -; - -/* - Get the network of a managed account - - # Safety - - - `account` must be a valid pointer to an FFIManagedCoreAccount instance - - Returns `FFINetwork::Mainnet` if the account is null - */ - FFINetwork managed_core_account_get_network(const FFIManagedCoreAccount *account) ; - -/* - Get the parent wallet ID of a managed account - - Note: ManagedAccount doesn't store the parent wallet ID directly. - The wallet ID is typically known from the context (e.g., when getting the account from a managed wallet). - - # Safety - - - `wallet_id` must be a valid pointer to a 32-byte wallet ID buffer that was provided by the caller - - The returned pointer is the same as the input pointer for convenience - - The caller must not free the returned pointer as it's the same as the input - */ - -const uint8_t *managed_core_account_get_parent_wallet_id(const uint8_t *wallet_id) -; - -/* - Get the account type of a managed account - - # Safety - - - `account` must be a valid pointer to an FFIManagedCoreAccount instance - - `index_out` must be a valid pointer to receive the account index (or null) - */ - -FFIAccountType managed_core_account_get_account_type(const FFIManagedCoreAccount *account, - unsigned int *index_out) -; - -/* - Check if a managed account is watch-only - - # Safety - - - `account` must be a valid pointer to an FFIManagedCoreAccount instance - */ - bool managed_core_account_get_is_watch_only(const FFIManagedCoreAccount *account) ; - -/* - Get the balance of a managed account - - # Safety - - - `account` must be a valid pointer to an FFIManagedCoreAccount instance - - `balance_out` must be a valid pointer to an FFIBalance structure - */ - -bool managed_core_account_get_balance(const FFIManagedCoreAccount *account, - FFIBalance *balance_out) -; - -/* - Get the number of transactions in a managed account - - # Safety - - - `account` must be a valid pointer to an FFIManagedCoreAccount instance - */ - unsigned int managed_core_account_get_transaction_count(const FFIManagedCoreAccount *account) ; - -/* - Get the number of UTXOs in a managed account - - # Safety - - - `account` must be a valid pointer to an FFIManagedCoreAccount instance - */ - unsigned int managed_core_account_get_utxo_count(const FFIManagedCoreAccount *account) ; - -/* - Get all transactions from a managed account - - Returns an array of FFITransactionRecord structures. - - # Safety - - - `account` must be a valid pointer to an FFIManagedCoreAccount instance - - `transactions_out` must be a valid pointer to receive the transactions array pointer - - `count_out` must be a valid pointer to receive the count - - The caller must free the returned array using `managed_core_account_free_transactions` - */ - -bool managed_core_account_get_transactions(const FFIManagedCoreAccount *account, - FFITransactionRecord **transactions_out, - size_t *count_out) -; - -/* - Free transactions array returned by managed_core_account_get_transactions - - # Safety - - - `transactions` must be a pointer returned by `managed_core_account_get_transactions` - - `count` must be the count returned by `managed_core_account_get_transactions` - - This function must only be called once per allocation - */ - void managed_core_account_free_transactions(FFITransactionRecord *transactions, size_t count) ; - -/* - Free a managed account handle - - # Safety - - - `account` must be a valid pointer to an FFIManagedCoreAccount that was allocated by this library - - The pointer must not be used after calling this function - - This function must only be called once per allocation - */ - void managed_core_account_free(FFIManagedCoreAccount *account) ; - -/* - Free a managed account result's error message (if any) - Note: This does NOT free the account handle itself - use managed_core_account_free for that - - # Safety - - - `result` must be a valid pointer to an FFIManagedCoreAccountResult - - The error_message field must be either null or a valid CString allocated by this library - - The caller must ensure the result pointer remains valid for the duration of this call - */ - void managed_core_account_result_free_error(FFIManagedCoreAccountResult *result) ; - -/* - Get number of accounts in a managed wallet - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `wallet_id` must be a valid pointer to a 32-byte wallet ID - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - -unsigned int managed_wallet_get_account_count(const FFIWalletManager *manager, - const uint8_t *wallet_id, - FFIError *error) -; - -/* - Get the account index from a managed account - - Returns the primary account index for Standard and CoinJoin accounts. - Returns 0 for account types that don't have an index (like Identity or Provider accounts). - - # Safety - - - `account` must be a valid pointer to an FFIManagedCoreAccount instance - */ - unsigned int managed_core_account_get_index(const FFIManagedCoreAccount *account) ; - -/* - Get the external address pool from a managed account - - This function returns the external (receive) address pool for Standard accounts. - Returns NULL for account types that don't have separate external/internal pools. - - # Safety - - - `account` must be a valid pointer to an FFIManagedCoreAccount instance - - The returned pool must be freed with `address_pool_free` when no longer needed - */ - -FFIAddressPool *managed_core_account_get_external_address_pool(const FFIManagedCoreAccount *account) -; - -/* - Get the internal address pool from a managed account - - This function returns the internal (change) address pool for Standard accounts. - Returns NULL for account types that don't have separate external/internal pools. - - # Safety - - - `account` must be a valid pointer to an FFIManagedCoreAccount instance - - The returned pool must be freed with `address_pool_free` when no longer needed - */ - -FFIAddressPool *managed_core_account_get_internal_address_pool(const FFIManagedCoreAccount *account) -; - -/* - Get an address pool from a managed account by type - - This function returns the appropriate address pool based on the pool type parameter. - For Standard accounts with External/Internal pool types, returns the corresponding pool. - For non-standard accounts with Single pool type, returns their single address pool. - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `account` must be a valid pointer to an FFIManagedCoreAccount instance - - `wallet_id` must be a valid pointer to a 32-byte wallet ID - - The returned pool must be freed with `address_pool_free` when no longer needed - */ - -FFIAddressPool *managed_core_account_get_address_pool(const FFIManagedCoreAccount *account, - FFIAddressPoolType pool_type) -; - -/* - Get a managed platform payment account from a managed wallet - - Platform Payment accounts (DIP-17) are identified by account index and key_class. - Returns a platform account handle that wraps the ManagedPlatformAccount. - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `wallet_id` must be a valid pointer to a 32-byte wallet ID - - The caller must ensure all pointers remain valid for the duration of this call - - The returned account must be freed with `managed_platform_account_free` when no longer needed - */ - -FFIManagedPlatformAccountResult managed_wallet_get_platform_payment_account(const FFIWalletManager *manager, - const uint8_t *wallet_id, - unsigned int account_index, - unsigned int key_class) -; - -/* - Get the network of a managed platform account - - # Safety - - - `account` must be a valid pointer to an FFIManagedPlatformAccount instance - - Returns `FFINetwork::Mainnet` if the account is null - */ - FFINetwork managed_platform_account_get_network(const FFIManagedPlatformAccount *account) ; - -/* - Get the account index of a managed platform account - - # Safety - - - `account` must be a valid pointer to an FFIManagedPlatformAccount instance - */ - unsigned int managed_platform_account_get_account_index(const FFIManagedPlatformAccount *account) ; - -/* - Get the key class of a managed platform account - - # Safety - - - `account` must be a valid pointer to an FFIManagedPlatformAccount instance - */ - unsigned int managed_platform_account_get_key_class(const FFIManagedPlatformAccount *account) ; - -/* - Get the total credit balance of a managed platform account - - Returns the balance in credits (1000 credits = 1 duff) - - # Safety - - - `account` must be a valid pointer to an FFIManagedPlatformAccount instance - */ - uint64_t managed_platform_account_get_credit_balance(const FFIManagedPlatformAccount *account) ; - -/* - Get the total balance in duffs of a managed platform account - - Returns the balance in duffs (credit_balance / 1000) - - # Safety - - - `account` must be a valid pointer to an FFIManagedPlatformAccount instance - */ - uint64_t managed_platform_account_get_duff_balance(const FFIManagedPlatformAccount *account) ; - -/* - Get the number of funded addresses in a managed platform account - - # Safety - - - `account` must be a valid pointer to an FFIManagedPlatformAccount instance - */ - -unsigned int managed_platform_account_get_funded_address_count(const FFIManagedPlatformAccount *account) -; - -/* - Get the total number of addresses in a managed platform account - - # Safety - - - `account` must be a valid pointer to an FFIManagedPlatformAccount instance - */ - -unsigned int managed_platform_account_get_total_address_count(const FFIManagedPlatformAccount *account) -; - -/* - Check if a managed platform account is watch-only - - # Safety - - - `account` must be a valid pointer to an FFIManagedPlatformAccount instance - */ - bool managed_platform_account_get_is_watch_only(const FFIManagedPlatformAccount *account) ; - -/* - Get the address pool from a managed platform account - - Platform accounts only have a single address pool. - - # Safety - - - `account` must be a valid pointer to an FFIManagedPlatformAccount instance - - The returned pool must be freed with `address_pool_free` when no longer needed - */ - -FFIAddressPool *managed_platform_account_get_address_pool(const FFIManagedPlatformAccount *account) -; - -/* - Free a managed platform account handle - - # Safety - - - `account` must be a valid pointer to an FFIManagedPlatformAccount that was allocated by this library - - The pointer must not be used after calling this function - - This function must only be called once per allocation - */ - -void managed_platform_account_free(FFIManagedPlatformAccount *account) -; - -/* - Free a managed platform account result's error message (if any) - Note: This does NOT free the account handle itself - use managed_platform_account_free for that - - # Safety - - - `result` must be a valid pointer to an FFIManagedPlatformAccountResult - - The error_message field must be either null or a valid CString allocated by this library - - The caller must ensure the result pointer remains valid for the duration of this call - */ - void managed_platform_account_result_free_error(FFIManagedPlatformAccountResult *result) ; - -/* - Get managed account collection for a specific network from wallet manager - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `wallet_id` must be a valid pointer to a 32-byte wallet ID - - `error` must be a valid pointer to an FFIError structure or null - - The returned pointer must be freed with `managed_account_collection_free` when no longer needed - */ - -FFIManagedCoreAccountCollection *managed_wallet_get_account_collection(const FFIWalletManager *manager, - const uint8_t *wallet_id, - FFIError *error) -; - -/* - Free a managed account collection handle - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection created by this library - - `collection` must not be used after calling this function - */ - -void managed_account_collection_free(FFIManagedCoreAccountCollection *collection) -; - -/* - Get a BIP44 account by index from the managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - The returned pointer must be freed with `managed_core_account_free` when no longer needed - */ - -FFIManagedCoreAccount *managed_account_collection_get_bip44_account(const FFIManagedCoreAccountCollection *collection, - unsigned int index) -; - -/* - Get all BIP44 account indices from managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - `out_indices` must be a valid pointer to store the indices array - - `out_count` must be a valid pointer to store the count - - The returned array must be freed with `free_u32_array` when no longer needed - */ - -bool managed_account_collection_get_bip44_indices(const FFIManagedCoreAccountCollection *collection, - unsigned int **out_indices, - size_t *out_count) -; - -/* - Get a BIP32 account by index from the managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - The returned pointer must be freed with `managed_core_account_free` when no longer needed - */ - -FFIManagedCoreAccount *managed_account_collection_get_bip32_account(const FFIManagedCoreAccountCollection *collection, - unsigned int index) -; - -/* - Get all BIP32 account indices from managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - `out_indices` must be a valid pointer to store the indices array - - `out_count` must be a valid pointer to store the count - - The returned array must be freed with `free_u32_array` when no longer needed - */ - -bool managed_account_collection_get_bip32_indices(const FFIManagedCoreAccountCollection *collection, - unsigned int **out_indices, - size_t *out_count) -; - -/* - Get a CoinJoin account by index from the managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - The returned pointer must be freed with `managed_core_account_free` when no longer needed - */ - -FFIManagedCoreAccount *managed_account_collection_get_coinjoin_account(const FFIManagedCoreAccountCollection *collection, - unsigned int index) -; - -/* - Get all CoinJoin account indices from managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - `out_indices` must be a valid pointer to store the indices array - - `out_count` must be a valid pointer to store the count - - The returned array must be freed with `free_u32_array` when no longer needed - */ - -bool managed_account_collection_get_coinjoin_indices(const FFIManagedCoreAccountCollection *collection, - unsigned int **out_indices, - size_t *out_count) -; - -/* - Get the identity registration account if it exists in managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - The returned pointer must be freed with `managed_core_account_free` when no longer needed - */ - -FFIManagedCoreAccount *managed_account_collection_get_identity_registration(const FFIManagedCoreAccountCollection *collection) -; - -/* - Check if identity registration account exists in managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - */ - -bool managed_account_collection_has_identity_registration(const FFIManagedCoreAccountCollection *collection) -; - -/* - Get an identity topup account by registration index from managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - The returned pointer must be freed with `managed_core_account_free` when no longer needed - */ - -FFIManagedCoreAccount *managed_account_collection_get_identity_topup(const FFIManagedCoreAccountCollection *collection, - unsigned int registration_index) -; - -/* - Get all identity topup registration indices from managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - `out_indices` must be a valid pointer to store the indices array - - `out_count` must be a valid pointer to store the count - - The returned array must be freed with `free_u32_array` when no longer needed - */ - -bool managed_account_collection_get_identity_topup_indices(const FFIManagedCoreAccountCollection *collection, - unsigned int **out_indices, - size_t *out_count) -; - -/* - Get the identity topup not bound account if it exists in managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - `manager` must be a valid pointer to an FFIWalletManager - - The returned pointer must be freed with `managed_core_account_free` when no longer needed - */ - -FFIManagedCoreAccount *managed_account_collection_get_identity_topup_not_bound(const FFIManagedCoreAccountCollection *collection) -; - -/* - Check if identity topup not bound account exists in managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - */ - -bool managed_account_collection_has_identity_topup_not_bound(const FFIManagedCoreAccountCollection *collection) -; - -/* - Get the identity invitation account if it exists in managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - The returned pointer must be freed with `managed_core_account_free` when no longer needed - */ - -FFIManagedCoreAccount *managed_account_collection_get_identity_invitation(const FFIManagedCoreAccountCollection *collection) -; - -/* - Check if identity invitation account exists in managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - */ - -bool managed_account_collection_has_identity_invitation(const FFIManagedCoreAccountCollection *collection) -; - -/* - Get the provider voting keys account if it exists in managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - The returned pointer must be freed with `managed_core_account_free` when no longer needed - */ - -FFIManagedCoreAccount *managed_account_collection_get_provider_voting_keys(const FFIManagedCoreAccountCollection *collection) -; - -/* - Check if provider voting keys account exists in managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - */ - -bool managed_account_collection_has_provider_voting_keys(const FFIManagedCoreAccountCollection *collection) -; - -/* - Get the provider owner keys account if it exists in managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - The returned pointer must be freed with `managed_core_account_free` when no longer needed - */ - -FFIManagedCoreAccount *managed_account_collection_get_provider_owner_keys(const FFIManagedCoreAccountCollection *collection) -; - -/* - Check if provider owner keys account exists in managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - */ - -bool managed_account_collection_has_provider_owner_keys(const FFIManagedCoreAccountCollection *collection) -; - -/* - Get the provider operator keys account if it exists in managed collection - Note: Returns null if the `bls` feature is not enabled - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - The returned pointer must be freed with `managed_core_account_free` when no longer needed (when BLS is enabled) - */ - -void *managed_account_collection_get_provider_operator_keys(const FFIManagedCoreAccountCollection *collection) -; - -/* - Check if provider operator keys account exists in managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - */ - -bool managed_account_collection_has_provider_operator_keys(const FFIManagedCoreAccountCollection *collection) -; - -/* - Get the provider platform keys account if it exists in managed collection - Note: Returns null if the `eddsa` feature is not enabled - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - The returned pointer must be freed with `managed_core_account_free` when no longer needed (when EdDSA is enabled) - */ - -void *managed_account_collection_get_provider_platform_keys(const FFIManagedCoreAccountCollection *collection) -; - -/* - Check if provider platform keys account exists in managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - */ - -bool managed_account_collection_has_provider_platform_keys(const FFIManagedCoreAccountCollection *collection) -; - -/* - Get a Platform Payment account by account index and key class from the managed collection - - Platform Payment accounts (DIP-17) are identified by two indices: - - account_index: The account' level in the derivation path - - key_class: The key_class' level in the derivation path (typically 0) - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - The returned pointer must be freed with `managed_platform_account_free` when no longer needed - */ - -FFIManagedPlatformAccount *managed_account_collection_get_platform_payment_account(const FFIManagedCoreAccountCollection *collection, - unsigned int account_index, - unsigned int key_class) -; - -/* - Get all Platform Payment account keys from managed collection - - Returns an array of FFIPlatformPaymentAccountKey structures. - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - `out_keys` must be a valid pointer to store the keys array - - `out_count` must be a valid pointer to store the count - - The returned array must be freed with `managed_account_collection_free_platform_payment_keys` when no longer needed - */ - -bool managed_account_collection_get_platform_payment_keys(const FFIManagedCoreAccountCollection *collection, - FFIPlatformPaymentAccountKey **out_keys, - size_t *out_count) -; - -/* - Free platform payment keys array returned by managed_account_collection_get_platform_payment_keys - - # Safety - - - `keys` must be a pointer returned by `managed_account_collection_get_platform_payment_keys` - - `count` must be the count returned by `managed_account_collection_get_platform_payment_keys` - - This function must only be called once per allocation - */ - -void managed_account_collection_free_platform_payment_keys(FFIPlatformPaymentAccountKey *keys, - size_t count) -; - -/* - Check if there are any Platform Payment accounts in the managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - */ - -bool managed_account_collection_has_platform_payment_accounts(const FFIManagedCoreAccountCollection *collection) -; - -/* - Get the number of Platform Payment accounts in the managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - */ - -unsigned int managed_account_collection_platform_payment_count(const FFIManagedCoreAccountCollection *collection) -; - -/* - Get the total number of accounts in the managed collection - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - */ - unsigned int managed_account_collection_count(const FFIManagedCoreAccountCollection *collection) ; - -/* - Get a human-readable summary of all accounts in the managed collection - - Returns a formatted string showing all account types and their indices. - The format is designed to be clear and readable for end users. - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - The returned string must be freed with `string_free` when no longer needed - - Returns null if the collection pointer is null - */ - char *managed_account_collection_summary(const FFIManagedCoreAccountCollection *collection) ; - -/* - Get structured account collection summary data for managed collection - - Returns a struct containing arrays of indices for each account type and boolean - flags for special accounts. This provides Swift with programmatic access to - account information. - - # Safety - - - `collection` must be a valid pointer to an FFIManagedCoreAccountCollection - - The returned pointer must be freed with `managed_account_collection_summary_free` when no longer needed - - Returns null if the collection pointer is null - */ - -FFIManagedCoreAccountCollectionSummary *managed_account_collection_summary_data(const FFIManagedCoreAccountCollection *collection) -; - -/* - Free a managed account collection summary and all its allocated memory - - # Safety - - - `summary` must be a valid pointer to an FFIManagedCoreAccountCollectionSummary created by `managed_account_collection_summary_data` - - `summary` must not be used after calling this function - */ - -void managed_account_collection_summary_free(FFIManagedCoreAccountCollectionSummary *summary) -; - -/* - Get the next unused receive address - - Generates the next unused receive address for the specified account. - This properly manages address gaps and updates the managed wallet state. - - # Safety - - - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - - `wallet` must be a valid pointer to an FFIWallet - - `error` must be a valid pointer to an FFIError - - The returned string must be freed by the caller - */ - -char *managed_wallet_get_next_bip44_receive_address(FFIManagedWalletInfo *managed_wallet, - const FFIWallet *wallet, - unsigned int account_index, - FFIError *error) -; - -/* - Get the next unused change address - - Generates the next unused change address for the specified account. - This properly manages address gaps and updates the managed wallet state. - - # Safety - - - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - - `wallet` must be a valid pointer to an FFIWallet - - `error` must be a valid pointer to an FFIError - - The returned string must be freed by the caller - */ - -char *managed_wallet_get_next_bip44_change_address(FFIManagedWalletInfo *managed_wallet, - const FFIWallet *wallet, - unsigned int account_index, - FFIError *error) -; - -/* - Get BIP44 external (receive) addresses in the specified range - - Returns external addresses from start_index (inclusive) to end_index (exclusive). - If addresses in the range haven't been generated yet, they will be generated. - - # Safety - - - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - - `wallet` must be a valid pointer to an FFIWallet - - `addresses_out` must be a valid pointer to store the address array pointer - - `count_out` must be a valid pointer to store the count - - `error` must be a valid pointer to an FFIError - - Free the result with address_array_free(addresses_out, count_out) - */ - -bool managed_wallet_get_bip_44_external_address_range(FFIManagedWalletInfo *managed_wallet, - const FFIWallet *wallet, - unsigned int account_index, - unsigned int start_index, - unsigned int end_index, - char ***addresses_out, - size_t *count_out, - FFIError *error) -; - -/* - Get BIP44 internal (change) addresses in the specified range - - Returns internal addresses from start_index (inclusive) to end_index (exclusive). - If addresses in the range haven't been generated yet, they will be generated. - - # Safety - - - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - - `wallet` must be a valid pointer to an FFIWallet - - `addresses_out` must be a valid pointer to store the address array pointer - - `count_out` must be a valid pointer to store the count - - `error` must be a valid pointer to an FFIError - - Free the result with address_array_free(addresses_out, count_out) - */ - -bool managed_wallet_get_bip_44_internal_address_range(FFIManagedWalletInfo *managed_wallet, - const FFIWallet *wallet, - unsigned int account_index, - unsigned int start_index, - unsigned int end_index, - char ***addresses_out, - size_t *count_out, - FFIError *error) -; - -/* - Get wallet balance from managed wallet info - - Returns the balance breakdown including confirmed, unconfirmed, immature, locked, and total amounts. - - # Safety - - - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - - `confirmed_out` must be a valid pointer to store the confirmed balance - - `unconfirmed_out` must be a valid pointer to store the unconfirmed balance - - `immature_out` must be a valid pointer to store the immature balance - - `locked_out` must be a valid pointer to store the locked balance - - `total_out` must be a valid pointer to store the total balance - - `error` must be a valid pointer to an FFIError - */ - -bool managed_wallet_get_balance(const FFIManagedWalletInfo *managed_wallet, - uint64_t *confirmed_out, - uint64_t *unconfirmed_out, - uint64_t *immature_out, - uint64_t *locked_out, - uint64_t *total_out, - FFIError *error) -; - -/* - Get current synced height from wallet info - - # Safety - - - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - -unsigned int managed_wallet_synced_height(const FFIManagedWalletInfo *managed_wallet, - FFIError *error) -; - -/* - Free managed wallet info - - # Safety - - - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo or null - - After calling this function, the pointer becomes invalid and must not be used - */ - void managed_wallet_free(FFIManagedWalletInfo *managed_wallet) ; - -/* - Free managed wallet info returned by wallet_manager_get_managed_wallet_info - - # Safety - - - `wallet_info` must be a valid pointer returned by wallet_manager_get_managed_wallet_info or null - - After calling this function, the pointer becomes invalid and must not be used - */ - void managed_wallet_info_free(FFIManagedWalletInfo *wallet_info) ; - -/* - Generate a new mnemonic with specified word count (12, 15, 18, 21, or 24) - */ - char *mnemonic_generate(unsigned int word_count, FFIError *error) ; - -/* - Generate a new mnemonic with specified language and word count - */ - -char *mnemonic_generate_with_language(unsigned int word_count, - FFILanguage language, - FFIError *error) -; - -/* - Validate a mnemonic phrase - - # Safety - - - `mnemonic` must be a valid null-terminated C string or null - - `error` must be a valid pointer to an FFIError - */ - bool mnemonic_validate(const char *mnemonic, FFIError *error) ; - -/* - Convert mnemonic to seed with optional passphrase - - # Safety - - - `mnemonic` must be a valid null-terminated C string - - `passphrase` must be a valid null-terminated C string or null - - `seed_out` must be a valid pointer to a buffer of at least 64 bytes - - `seed_len` must be a valid pointer to store the seed length - - `error` must be a valid pointer to an FFIError - */ - -bool mnemonic_to_seed(const char *mnemonic, - const char *passphrase, - uint8_t *seed_out, - size_t *seed_len, - FFIError *error) -; - -/* - Get word count from mnemonic - - # Safety - - - `mnemonic` must be a valid null-terminated C string or null - - `error` must be a valid pointer to an FFIError - */ - unsigned int mnemonic_word_count(const char *mnemonic, FFIError *error) ; - -/* - Free a mnemonic string - - # Safety - - - `mnemonic` must be a valid pointer created by mnemonic generation functions or null - - After calling this function, the pointer becomes invalid - */ - void mnemonic_free(char *mnemonic) ; - -/* - Build and sign a transaction using the wallet's managed info - - This is the recommended way to build transactions. It handles: - - UTXO selection using coin selection algorithms - - Fee calculation - - Change address generation - - Transaction signing - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager - - `wallet` must be a valid pointer to an FFIWallet - - `account_index` must be a valid BIP44 account index present in the wallet - - `outputs` must be a valid pointer to an array of FFITxOutput with at least `outputs_count` elements - - `fee_rate` must be a valid variant of FFIFeeRate - - `fee_out` must be a valid, non-null pointer to a `u64`; on success it receives the - calculated transaction fee in duffs - - `tx_bytes_out` must be a valid pointer to store the transaction bytes pointer - - `tx_len_out` must be a valid pointer to store the transaction length - - `error` must be a valid pointer to an FFIError - - The returned transaction bytes must be freed with `transaction_bytes_free` - */ - -bool wallet_build_and_sign_transaction(const FFIWalletManager *manager, - const FFIWallet *wallet, - uint32_t account_index, - const FFITxOutput *outputs, - size_t outputs_count, - uint64_t fee_per_kb, - uint64_t *fee_out, - uint8_t **tx_bytes_out, - size_t *tx_len_out, - FFIError *error) -; - -/* - Check if a transaction belongs to the wallet using ManagedWalletInfo - - # Safety - - - `wallet` must be a valid mutable pointer to an FFIWallet - - `tx_bytes` must be a valid pointer to transaction bytes with at least `tx_len` bytes - - `inputs_spent_out` must be a valid pointer to store the spent inputs count - - `addresses_used_out` must be a valid pointer to store the used addresses count - - `new_balance_out` must be a valid pointer to store the new balance - - `new_address_out` must be a valid pointer to store the address array pointer - - `new_address_count_out` must be a valid pointer to store the address count - - `error` must be a valid pointer to an FFIError - */ - -bool wallet_check_transaction(FFIWallet *wallet, - const uint8_t *tx_bytes, - size_t tx_len, - FFITransactionContext context_type, - uint32_t block_height, - const uint8_t *block_hash, - uint64_t timestamp, - bool update_state, - FFITransactionCheckResult *result_out, - FFIError *error) -; - -/* - Free transaction bytes - - # Safety - - - `tx_bytes` must be a valid pointer created by transaction functions or null - - After calling this function, the pointer becomes invalid - */ - void transaction_bytes_free(uint8_t *tx_bytes) ; - -/* - Create a new empty transaction - - # Returns - - Pointer to FFITransaction on success - - NULL on error - */ - FFITransaction *transaction_create(void) ; - -/* - Add an input to a transaction - - # Safety - - `tx` must be a valid pointer to an FFITransaction - - `input` must be a valid pointer to an FFITxIn - - # Returns - - 0 on success - - -1 on error - */ - int32_t transaction_add_input(FFITransaction *tx, const FFITxIn *input) ; - -/* - Add an output to a transaction - - # Safety - - `tx` must be a valid pointer to an FFITransaction - - `output` must be a valid pointer to an FFITxOut - - # Returns - - 0 on success - - -1 on error - */ - int32_t transaction_add_output(FFITransaction *tx, const FFITxOut *output) ; - -/* - Get the transaction ID - - # Safety - - `tx` must be a valid pointer to an FFITransaction - - `txid_out` must be a valid pointer to a buffer of at least 32 bytes - - # Returns - - 0 on success - - -1 on error - */ - int32_t transaction_get_txid(const FFITransaction *tx, uint8_t *txid_out) ; - -/* - Get transaction ID from raw transaction bytes - - # Safety - - `tx_bytes` must be a valid pointer to transaction bytes - - `tx_len` must be the correct length of the transaction - - `error` must be a valid pointer to an FFIError - - # Returns - - Pointer to null-terminated hex string of TXID (must be freed with string_free) - - NULL on error - */ - char *transaction_get_txid_from_bytes(const uint8_t *tx_bytes, size_t tx_len, FFIError *error) ; - -/* - Serialize a transaction - - # Safety - - `tx` must be a valid pointer to an FFITransaction - - `out_buf` can be NULL to get size only - - `out_len` must be a valid pointer to store the size - - # Returns - - 0 on success - - -1 on error - */ - int32_t transaction_serialize(const FFITransaction *tx, uint8_t *out_buf, uint32_t *out_len) ; - -/* - Deserialize a transaction - - # Safety - - `data` must be a valid pointer to serialized transaction data - - `len` must be the correct length of the data - - # Returns - - Pointer to FFITransaction on success - - NULL on error - */ - FFITransaction *transaction_deserialize(const uint8_t *data, uint32_t len) ; - -/* - Destroy a transaction - - # Safety - - `tx` must be a valid pointer to an FFITransaction created by transaction functions or null - - After calling this function, the pointer becomes invalid - */ - void transaction_destroy(FFITransaction *tx) ; - -/* - Calculate signature hash for an input - - # Safety - - `tx` must be a valid pointer to an FFITransaction - - `script_pubkey` must be a valid pointer to the script pubkey - - `hash_out` must be a valid pointer to a buffer of at least 32 bytes - - # Returns - - 0 on success - - -1 on error - */ - -int32_t transaction_sighash(const FFITransaction *tx, - uint32_t input_index, - const uint8_t *script_pubkey, - uint32_t script_pubkey_len, - uint32_t sighash_type, - uint8_t *hash_out) -; - -/* - Sign a transaction input - - # Safety - - `tx` must be a valid pointer to an FFITransaction - - `private_key` must be a valid pointer to a 32-byte private key - - `script_pubkey` must be a valid pointer to the script pubkey - - # Returns - - 0 on success - - -1 on error - */ - -int32_t transaction_sign_input(FFITransaction *tx, - uint32_t input_index, - const uint8_t *private_key, - const uint8_t *script_pubkey, - uint32_t script_pubkey_len, - uint32_t sighash_type) -; - -/* - Create a P2PKH script pubkey - - # Safety - - `pubkey_hash` must be a valid pointer to a 20-byte public key hash - - `out_buf` can be NULL to get size only - - `out_len` must be a valid pointer to store the size - - # Returns - - 0 on success - - -1 on error - */ - int32_t script_p2pkh(const uint8_t *pubkey_hash, uint8_t *out_buf, uint32_t *out_len) ; - -/* - Extract public key hash from P2PKH address - - # Safety - - `address` must be a valid pointer to a null-terminated C string - - `hash_out` must be a valid pointer to a buffer of at least 20 bytes - - # Returns - - 0 on success - - -1 on error - */ - int32_t address_to_pubkey_hash(const char *address, FFINetwork network, uint8_t *hash_out) ; - -/* - Create a managed wallet from a regular wallet - - This creates a ManagedWalletInfo instance from a Wallet, which includes - address pools and transaction checking capabilities. - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet - - `error` must be a valid pointer to an FFIError or null - - The returned pointer must be freed with `managed_wallet_info_free` (or `ffi_managed_wallet_free` for compatibility) - */ - -FFIManagedWalletInfo *wallet_create_managed_wallet(const FFIWallet *wallet, - FFIError *error) -; - -/* - Check if a transaction belongs to the wallet - - This function checks a transaction against all relevant account types in the wallet - and returns detailed information about which accounts are affected. - - # Safety - - - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - - `wallet` must be a valid pointer to an FFIWallet (needed for address generation and DashPay queries) - - `tx_bytes` must be a valid pointer to transaction bytes with at least `tx_len` bytes - - `result_out` must be a valid pointer to store the result - - `error` must be a valid pointer to an FFIError - - The affected_accounts array in the result must be freed with `transaction_check_result_free` - */ - -bool managed_wallet_check_transaction(FFIManagedWalletInfo *managed_wallet, - FFIWallet *wallet, - const uint8_t *tx_bytes, - size_t tx_len, - FFITransactionContext context_type, - unsigned int block_height, - const uint8_t *block_hash, - uint64_t timestamp, - bool update_state, - FFITransactionCheckResult *result_out, - FFIError *error) -; - -/* - Free a transaction check result - - # Safety - - - `result` must be a valid pointer to an FFITransactionCheckResult - - This function must only be called once per result - */ - void transaction_check_result_free(FFITransactionCheckResult *result) ; - -/* - Free a managed wallet (FFIManagedWalletInfo type) - - # Safety - - - `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - - This function must only be called once per managed wallet - */ - void ffi_managed_wallet_free(FFIManagedWalletInfo *managed_wallet) ; - -/* - Get the transaction classification for routing - - Returns a string describing the transaction type (e.g., "Standard", "CoinJoin", - "AssetLock", "AssetUnlock", "ProviderRegistration", etc.) - - # Safety - - - `tx_bytes` must be a valid pointer to transaction bytes with at least `tx_len` bytes - - `error` must be a valid pointer to an FFIError or null - - The returned string must be freed by the caller - */ - char *transaction_classify(const uint8_t *tx_bytes, size_t tx_len, FFIError *error) ; - - const char *ffi_network_get_name(FFINetwork network) ; - -/* - Free a string - - # Safety - - - `s` must be a valid pointer created by C string creation functions or null - - After calling this function, the pointer becomes invalid - */ - void string_free(char *s) ; - -/* - Get all UTXOs from managed wallet info - - # Safety - - - `managed_info` must be a valid pointer to an FFIManagedWalletInfo instance - - `utxos_out` must be a valid pointer to store the UTXO array pointer - - `count_out` must be a valid pointer to store the UTXO count - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - - The returned UTXO array must be freed with `utxo_array_free` when no longer needed - */ - -bool managed_wallet_get_utxos(const FFIManagedWalletInfo *managed_info, - FFIUTXO **utxos_out, - size_t *count_out, - FFIError *error) -; - -/* - Get all UTXOs (deprecated - use managed_wallet_get_utxos instead) - - # Safety - - This function is deprecated and returns an empty list. - Use `managed_wallet_get_utxos` with a ManagedWalletInfo instead. - */ - -bool wallet_get_utxos(const FFIWallet *_wallet, - FFIUTXO **utxos_out, - size_t *count_out, - FFIError *error) -; - -/* - Free UTXO array - - # Safety - - - `utxos` must be a valid pointer to an array of FFIUTXO structs allocated by this library - - `count` must match the number of UTXOs in the array - - The pointer must not be used after calling this function - - This function must only be called once per array - */ - void utxo_array_free(FFIUTXO *utxos, size_t count) ; - -/* - Create a new wallet from mnemonic with options - - # Safety - - - `mnemonic` must be a valid pointer to a null-terminated C string - - `passphrase` must be a valid pointer to a null-terminated C string or null - - `account_options` must be a valid pointer to FFIWalletAccountCreationOptions or null - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - - The returned pointer must be freed with `wallet_free` when no longer needed - */ - -FFIWallet *wallet_create_from_mnemonic_with_options(const char *mnemonic, - const char *passphrase, - FFINetwork network, - const FFIWalletAccountCreationOptions *account_options, - FFIError *error) -; - -/* - Create a new wallet from mnemonic (backward compatibility - single network) - - # Safety - - - `mnemonic` must be a valid pointer to a null-terminated C string - - `passphrase` must be a valid pointer to a null-terminated C string or null - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - - The returned pointer must be freed with `wallet_free` when no longer needed - */ - -FFIWallet *wallet_create_from_mnemonic(const char *mnemonic, - const char *passphrase, - FFINetwork network, - FFIError *error) -; - -/* - Create a new wallet from seed with options - - # Safety - - - `seed` must be a valid pointer to a byte array of `seed_len` length - - `account_options` must be a valid pointer to FFIWalletAccountCreationOptions or null - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - -FFIWallet *wallet_create_from_seed_with_options(const uint8_t *seed, - size_t seed_len, - FFINetwork network, - const FFIWalletAccountCreationOptions *account_options, - FFIError *error) -; - -/* - Create a new wallet from seed (backward compatibility) - - # Safety - - - `seed` must be a valid pointer to a byte array of `seed_len` length - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - -FFIWallet *wallet_create_from_seed(const uint8_t *seed, - size_t seed_len, - FFINetwork network, - FFIError *error) -; - -/* - Create a new random wallet with options - - # Safety - - - `account_options` must be a valid pointer to FFIWalletAccountCreationOptions or null - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - -FFIWallet *wallet_create_random_with_options(FFINetwork network, - const FFIWalletAccountCreationOptions *account_options, - FFIError *error) -; - -/* - Create a new random wallet (backward compatibility) - - # Safety - - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure the pointer remains valid for the duration of this call - */ - FFIWallet *wallet_create_random(FFINetwork network, FFIError *error) ; - -/* - Get wallet ID (32-byte hash) - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet - - `id_out` must be a valid pointer to a 32-byte buffer - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - bool wallet_get_id(const FFIWallet *wallet, uint8_t *id_out, FFIError *error) ; - -/* - Check if wallet has mnemonic - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet instance - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - bool wallet_has_mnemonic(const FFIWallet *wallet, FFIError *error) ; - -/* - Check if wallet is watch-only - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet instance - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - bool wallet_is_watch_only(const FFIWallet *wallet, FFIError *error) ; - -/* - Get extended public key for account - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet instance - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - - The returned C string must be freed by the caller when no longer needed - */ - char *wallet_get_xpub(const FFIWallet *wallet, unsigned int account_index, FFIError *error) ; - -/* - Free a wallet - - # Safety - - - `wallet` must be a valid pointer to an FFIWallet that was created by this library - - The pointer must not be used after calling this function - - This function must only be called once per wallet - */ - void wallet_free(FFIWallet *wallet) ; - -/* - Free a const wallet handle - - This is a const-safe wrapper for wallet_free() that accepts a const pointer. - Use this function when you have a *const FFIWallet that needs to be freed, - such as wallets returned from wallet_manager_get_wallet(). - - # Safety - - - `wallet` must be a valid pointer created by wallet creation functions or null - - After calling this function, the pointer becomes invalid - - This function must only be called once per wallet - - The wallet must have been allocated by this library (not stack or static memory) - */ - void wallet_free_const(const FFIWallet *wallet) ; - -/* - Add an account to the wallet without xpub - - # Safety - - This function dereferences a raw pointer to FFIWallet. - The caller must ensure that: - - The wallet pointer is either null or points to a valid FFIWallet - - The FFIWallet remains valid for the duration of this call - - # Note - - This function does NOT support the following account types: - - `PlatformPayment`: Use `wallet_add_platform_payment_account()` instead - - `DashpayReceivingFunds`: Use `wallet_add_dashpay_receiving_account()` instead - - `DashpayExternalAccount`: Use `wallet_add_dashpay_external_account_with_xpub_bytes()` instead - */ - -FFIAccountResult wallet_add_account(FFIWallet *wallet, - FFIAccountType account_type, - unsigned int account_index) -; - -/* - Add a DashPay receiving funds account - - # Safety - - `wallet` must be a valid pointer - - `user_identity_id` and `friend_identity_id` must each point to 32 bytes - */ - -FFIAccountResult wallet_add_dashpay_receiving_account(FFIWallet *wallet, - unsigned int account_index, - const uint8_t *user_identity_id, - const uint8_t *friend_identity_id) -; - -/* - Add a DashPay external (watch-only) account with xpub bytes - - # Safety - - `wallet` must be valid, `xpub_bytes` must point to `xpub_len` bytes - - `user_identity_id` and `friend_identity_id` must each point to 32 bytes - */ - -FFIAccountResult wallet_add_dashpay_external_account_with_xpub_bytes(FFIWallet *wallet, - unsigned int account_index, - const uint8_t *user_identity_id, - const uint8_t *friend_identity_id, - const uint8_t *xpub_bytes, - size_t xpub_len) -; - -/* - Add an account to the wallet with xpub as byte array - - # Safety - - This function dereferences raw pointers. - The caller must ensure that: - - The wallet pointer is either null or points to a valid FFIWallet - - The xpub_bytes pointer is either null or points to at least xpub_len bytes - - The FFIWallet remains valid for the duration of this call - - # Note - - This function does NOT support the following account types: - - `PlatformPayment`: Use `wallet_add_platform_payment_account()` instead - - `DashpayReceivingFunds`: Use `wallet_add_dashpay_receiving_account()` instead - - `DashpayExternalAccount`: Use `wallet_add_dashpay_external_account_with_xpub_bytes()` instead - */ - -FFIAccountResult wallet_add_account_with_xpub_bytes(FFIWallet *wallet, - FFIAccountType account_type, - unsigned int account_index, - const uint8_t *xpub_bytes, - size_t xpub_len) -; - -/* - Add an account to the wallet with xpub as string - - # Safety - - This function dereferences raw pointers. - The caller must ensure that: - - The wallet pointer is either null or points to a valid FFIWallet - - The xpub_string pointer is either null or points to a valid null-terminated C string - - The FFIWallet remains valid for the duration of this call - - # Note - - This function does NOT support the following account types: - - `PlatformPayment`: Use `wallet_add_platform_payment_account()` instead - - `DashpayReceivingFunds`: Use `wallet_add_dashpay_receiving_account()` instead - - `DashpayExternalAccount`: Use `wallet_add_dashpay_external_account_with_xpub_bytes()` instead - */ - -FFIAccountResult wallet_add_account_with_string_xpub(FFIWallet *wallet, - FFIAccountType account_type, - unsigned int account_index, - const char *xpub_string) -; - -/* - Add a Platform Payment account (DIP-17) to the wallet - - Platform Payment accounts use the derivation path: - `m/9'/coin_type'/17'/account'/key_class'/index` - - # Arguments - * `wallet` - Pointer to the wallet - * `account_index` - The account index (hardened) in the derivation path - * `key_class` - The key class (hardened) - typically 0' for main addresses - - # Safety - - This function dereferences a raw pointer to FFIWallet. - The caller must ensure that: - - The wallet pointer is either null or points to a valid FFIWallet - - The FFIWallet remains valid for the duration of this call - */ - -FFIAccountResult wallet_add_platform_payment_account(FFIWallet *wallet, - unsigned int account_index, - unsigned int key_class) -; - -/* - Describe the wallet manager for a given network and return a newly - allocated C string. - - # Safety - - `manager` must be a valid pointer to an `FFIWalletManager` - - Callers must free the returned string with `wallet_manager_free_string` - */ - char *wallet_manager_describe(const FFIWalletManager *manager, FFIError *error) ; - -/* - Free a string previously returned by wallet manager APIs. - - # Safety - - `value` must be either null or a pointer obtained from - `wallet_manager_describe` (or other wallet manager FFI helpers that - specify this free function). - - The pointer must not be used after this call returns. - */ - void wallet_manager_free_string(char *value) ; - -/* - Create a new wallet manager - */ - FFIWalletManager *wallet_manager_create(FFINetwork network, FFIError *error) ; - -/* - Add a wallet from mnemonic to the manager with options - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `mnemonic` must be a valid pointer to a null-terminated C string - - `passphrase` must be a valid pointer to a null-terminated C string or null - - `account_options` must be a valid pointer to FFIWalletAccountCreationOptions or null - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - -bool wallet_manager_add_wallet_from_mnemonic_with_options(FFIWalletManager *manager, - const char *mnemonic, - const char *passphrase, - const FFIWalletAccountCreationOptions *account_options, - FFIError *error) -; - -/* - Add a wallet from mnemonic to the manager (backward compatibility) - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `mnemonic` must be a valid pointer to a null-terminated C string - - `passphrase` must be a valid pointer to a null-terminated C string or null - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - -bool wallet_manager_add_wallet_from_mnemonic(FFIWalletManager *manager, - const char *mnemonic, - const char *passphrase, - FFIError *error) -; - -/* - Add a wallet from mnemonic to the manager and return serialized bytes - - Creates a wallet from a mnemonic phrase, adds it to the manager, optionally downgrading it - to a pubkey-only wallet (watch-only or externally signable), and returns the serialized wallet bytes. - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `mnemonic` must be a valid pointer to a null-terminated C string - - `passphrase` must be a valid pointer to a null-terminated C string or null - - `birth_height` is the block height to start syncing from (0 = sync from genesis) - - `account_options` must be a valid pointer to FFIWalletAccountCreationOptions or null - - `downgrade_to_pubkey_wallet` if true, creates a watch-only or externally signable wallet - - `allow_external_signing` if true AND downgrade_to_pubkey_wallet is true, creates an externally signable wallet - - `wallet_bytes_out` must be a valid pointer to a pointer that will receive the serialized bytes - - `wallet_bytes_len_out` must be a valid pointer that will receive the byte length - - `wallet_id_out` must be a valid pointer to a 32-byte array that will receive the wallet ID - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - - The caller must free the returned wallet_bytes using wallet_manager_free_wallet_bytes() - */ - -bool wallet_manager_add_wallet_from_mnemonic_return_serialized_bytes(FFIWalletManager *manager, - const char *mnemonic, - const char *passphrase, - unsigned int birth_height, - const FFIWalletAccountCreationOptions *account_options, - bool downgrade_to_pubkey_wallet, - bool allow_external_signing, - uint8_t **wallet_bytes_out, - size_t *wallet_bytes_len_out, - uint8_t *wallet_id_out, - FFIError *error) -; - -/* - Free wallet bytes buffer - - # Safety - - - `wallet_bytes` must be a valid pointer to a buffer allocated by wallet_manager_add_wallet_from_mnemonic_return_serialized_bytes - - `bytes_len` must match the original allocation size - - The pointer must not be used after calling this function - - This function must only be called once per buffer - */ - -void wallet_manager_free_wallet_bytes(uint8_t *wallet_bytes, - size_t bytes_len) -; - -/* - Import a wallet from bincode-serialized bytes - - Deserializes a wallet from bytes and adds it to the manager. - Returns a 32-byte wallet ID on success. - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `wallet_bytes` must be a valid pointer to bincode-serialized wallet bytes - - `wallet_bytes_len` must be the exact length of the wallet bytes - - `wallet_id_out` must be a valid pointer to a 32-byte array that will receive the wallet ID - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - -bool wallet_manager_import_wallet_from_bytes(FFIWalletManager *manager, - const uint8_t *wallet_bytes, - size_t wallet_bytes_len, - uint8_t *wallet_id_out, - FFIError *error) -; - -/* - Get wallet IDs - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager - - `wallet_ids_out` must be a valid pointer to a pointer that will receive the wallet IDs - - `count_out` must be a valid pointer to receive the count - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - -bool wallet_manager_get_wallet_ids(const FFIWalletManager *manager, - uint8_t **wallet_ids_out, - size_t *count_out, - FFIError *error) -; - -/* - Get a wallet from the manager - - Returns a reference to the wallet if found - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `wallet_id` must be a valid pointer to a 32-byte wallet ID - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - - The returned wallet must be freed with wallet_free_const() - */ - -const FFIWallet *wallet_manager_get_wallet(const FFIWalletManager *manager, - const uint8_t *wallet_id, - FFIError *error) -; - -/* - Get managed wallet info from the manager - - Returns a reference to the managed wallet info if found - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `wallet_id` must be a valid pointer to a 32-byte wallet ID - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - - The returned managed wallet info must be freed with managed_wallet_info_free() - */ - -FFIManagedWalletInfo *wallet_manager_get_managed_wallet_info(const FFIWalletManager *manager, - const uint8_t *wallet_id, - FFIError *error) -; - -/* - Get wallet balance - - Returns the confirmed and unconfirmed balance for a specific wallet - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `wallet_id` must be a valid pointer to a 32-byte wallet ID - - `confirmed_out` must be a valid pointer to a u64 (maps to C uint64_t) - - `unconfirmed_out` must be a valid pointer to a u64 (maps to C uint64_t) - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - -bool wallet_manager_get_wallet_balance(const FFIWalletManager *manager, - const uint8_t *wallet_id, - uint64_t *confirmed_out, - uint64_t *unconfirmed_out, - FFIError *error) -; - -/* - Process a transaction through all wallets - - Checks a transaction against all wallets and updates their states if relevant. - Returns true if the transaction was relevant to at least one wallet. - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `tx_bytes` must be a valid pointer to transaction bytes - - `tx_len` must be the length of the transaction bytes - - `context` must be a valid pointer to FFITransactionContextDetails - - `update_state_if_found` indicates whether to update wallet state when transaction is relevant - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - -bool wallet_manager_process_transaction(FFIWalletManager *manager, - const uint8_t *tx_bytes, - size_t tx_len, - const FFITransactionContextDetails *context, - bool update_state_if_found, - FFIError *error) -; - -/* - Get the network for this wallet manager - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - FFINetwork wallet_manager_network(const FFIWalletManager *manager, FFIError *error) ; - -/* - Get current height for a network - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - unsigned int wallet_manager_current_height(const FFIWalletManager *manager, FFIError *error) ; - -/* - Get wallet count - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager instance - - `error` must be a valid pointer to an FFIError structure or null - - The caller must ensure all pointers remain valid for the duration of this call - */ - size_t wallet_manager_wallet_count(const FFIWalletManager *manager, FFIError *error) ; - -/* - Free wallet manager - - # Safety - - - `manager` must be a valid pointer to an FFIWalletManager that was created by this library - - The pointer must not be used after calling this function - - This function must only be called once per manager - */ - void wallet_manager_free(FFIWalletManager *manager) ; - -/* - Free wallet IDs buffer - - # Safety - - - `wallet_ids` must be a valid pointer to a buffer allocated by this library - - `count` must match the number of wallet IDs in the buffer - - The pointer must not be used after calling this function - - This function must only be called once per buffer - */ - void wallet_manager_free_wallet_ids(uint8_t *wallet_ids, size_t count) ; - -/* - Free address array - - # Safety - - - `addresses` must be a valid pointer to an array of C string pointers allocated by this library - - `count` must match the original allocation size - - Each address pointer in the array must be either null or a valid C string allocated by this library - - The pointers must not be used after calling this function - - This function must only be called once per allocation - */ - -void wallet_manager_free_addresses(char **addresses, - size_t count) -; - -/* - Encrypt a private key with BIP38 - - # Safety - - This function is unsafe because it dereferences raw pointers: - - `private_key` must be a valid, null-terminated C string - - `passphrase` must be a valid, null-terminated C string - - `error` must be a valid pointer to an FFIError or null - */ - char *bip38_encrypt_private_key(const char *private_key, const char *passphrase, FFIError *error) ; - -/* - Decrypt a BIP38 encrypted private key - - # Safety - - This function is unsafe because it dereferences raw pointers: - - `encrypted_key` must be a valid, null-terminated C string - - `passphrase` must be a valid, null-terminated C string - - `error` must be a valid pointer to an FFIError or null - */ - -char *bip38_decrypt_private_key(const char *encrypted_key, - const char *passphrase, - FFIError *error) -; - -#ifdef __cplusplus -} // extern "C" -#endif // __cplusplus - -#endif /* KEY_WALLET_FFI_H */