From f10cc9fcbb3fde75e6234fcf147efb5ff64b08f9 Mon Sep 17 00:00:00 2001 From: xdustinface Date: Thu, 23 Apr 2026 09:19:59 +1000 Subject: [PATCH 1/2] refactor(wallet): rename synced_height to last_processed_height Rename the wallet-applied chain height from synced_height to last_processed_height across key-wallet, key-wallet-manager, key-wallet-ffi, and dash-spv call sites. This also updates the FFI symbol managed_wallet_last_processed_height and picks up rename sites introduced by newer v0.42-dev changes. filter_committed_height is left unchanged here so the next commit can rename that concept to synced_height with a clear diff. --- dash-spv/src/sync/blocks/manager.rs | 4 +- dash-spv/src/sync/filters/manager.rs | 10 +- key-wallet-ffi/FFI_API.md | 255 ++++++++---------- key-wallet-ffi/src/managed_wallet.rs | 6 +- key-wallet-ffi/src/transaction.rs | 2 +- key-wallet-ffi/src/utxo.rs | 2 +- key-wallet-ffi/src/utxo_tests.rs | 2 +- key-wallet-ffi/src/wallet_manager.rs | 2 +- key-wallet-ffi/src/wallet_manager_tests.rs | 2 +- .../examples/wallet_creation.rs | 6 +- key-wallet-manager/src/lib.rs | 12 +- key-wallet-manager/src/process_block.rs | 44 +-- .../src/test_utils/mock_wallet.rs | 24 +- key-wallet-manager/src/wallet_interface.rs | 16 +- key-wallet-manager/tests/integration_test.rs | 42 +-- .../tests/spv_integration_tests.rs | 11 +- key-wallet/src/managed_account/mod.rs | 13 +- key-wallet/src/tests/balance_tests.rs | 10 +- .../transaction_checking/wallet_checker.rs | 24 +- .../managed_wallet_info/asset_lock_builder.rs | 10 +- .../wallet_info_interface.rs | 27 +- key-wallet/src/wallet/metadata.rs | 4 +- 22 files changed, 259 insertions(+), 269 deletions(-) diff --git a/dash-spv/src/sync/blocks/manager.rs b/dash-spv/src/sync/blocks/manager.rs index 8ea4e2f59..45ffed61b 100644 --- a/dash-spv/src/sync/blocks/manager.rs +++ b/dash-spv/src/sync/blocks/manager.rs @@ -48,10 +48,10 @@ impl BlocksManager>, block_storage: Arc>, ) -> Self { - let synced_height = wallet.read().await.synced_height(); + let last_processed_height = wallet.read().await.last_processed_height(); let mut initial_progress = BlocksProgress::default(); - initial_progress.update_last_processed(synced_height); + initial_progress.update_last_processed(last_processed_height); Self { progress: initial_progress, diff --git a/dash-spv/src/sync/filters/manager.rs b/dash-spv/src/sync/filters/manager.rs index 15dcbcee3..b410df044 100644 --- a/dash-spv/src/sync/filters/manager.rs +++ b/dash-spv/src/sync/filters/manager.rs @@ -159,7 +159,7 @@ impl *mut FFIWal ``` **Description:** -Create a new wallet manager # Safety `error` must be a valid pointer to an `FFIError`. The returned pointer must be freed with `wallet_manager_free`. - -**Safety:** -`error` must be a valid pointer to an `FFIError`. The returned pointer must be freed with `wallet_manager_free`. +Create a new wallet manager **Module:** `wallet_manager` @@ -513,10 +510,10 @@ wallet_manager_current_height(manager: *const FFIWalletManager, error: *mut FFIE ``` **Description:** -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 - The caller must ensure all pointers remain valid for the duration of this call +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 **Safety:** -- `manager` must be a valid pointer to an FFIWalletManager - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call +- `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 **Module:** `wallet_manager` @@ -619,10 +616,10 @@ wallet_manager_get_managed_wallet_info(manager: *const FFIWalletManager, wallet_ ``` **Description:** -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 - 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() +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() **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 - 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() +- `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() **Module:** `wallet_manager` @@ -635,10 +632,10 @@ wallet_manager_get_wallet(manager: *const FFIWalletManager, wallet_id: *const u8 ``` **Description:** -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 - The caller must ensure all pointers remain valid for the duration of this call - The returned wallet must be freed with wallet_free_const() +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() **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 - The caller must ensure all pointers remain valid for the duration of this call - The returned wallet must be freed with wallet_free_const() +- `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() **Module:** `wallet_manager` @@ -651,10 +648,10 @@ wallet_manager_get_wallet_balance(manager: *const FFIWalletManager, wallet_id: * ``` **Description:** -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 - The caller must ensure all pointers remain valid for the duration of this call +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 **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 - The caller must ensure all pointers remain valid for the duration of this call +- `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 **Module:** `wallet_manager` @@ -667,10 +664,10 @@ wallet_manager_get_wallet_ids(manager: *const FFIWalletManager, wallet_ids_out: ``` **Description:** -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 - The caller must ensure all pointers remain valid for the duration of this call +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 **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 - The caller must ensure all pointers remain valid for the duration of this call +- `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 **Module:** `wallet_manager` @@ -693,10 +690,10 @@ wallet_manager_network(manager: *const FFIWalletManager, error: *mut FFIError,) ``` **Description:** -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 - The caller must ensure all pointers remain valid for the duration of this call +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 **Safety:** -- `manager` must be a valid pointer to an FFIWalletManager - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call +- `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 **Module:** `wallet_manager` @@ -709,10 +706,10 @@ wallet_manager_process_transaction(manager: *mut FFIWalletManager, tx_bytes: *co ``` **Description:** -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 FFITransactionContext - `update_state_if_found` indicates whether to update wallet state when transaction is relevant - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call +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 FFITransactionContext - `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 **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 FFITransactionContext - `update_state_if_found` indicates whether to update wallet state when transaction is relevant - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call +- `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 FFITransactionContext - `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 **Module:** `wallet_manager` @@ -725,10 +722,10 @@ wallet_manager_wallet_count(manager: *const FFIWalletManager, error: *mut FFIErr ``` **Description:** -Get wallet count # Safety - `manager` must be a valid pointer to an FFIWalletManager instance - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call +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 **Safety:** -- `manager` must be a valid pointer to an FFIWalletManager instance - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call +- `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 **Module:** `wallet_manager` @@ -891,10 +888,10 @@ managed_wallet_generate_addresses_to_index(managed_wallet: *mut FFIManagedWallet ``` **Description:** -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 +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 **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 +- `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 **Module:** `address_pool` @@ -923,10 +920,10 @@ managed_wallet_get_account_collection(manager: *const FFIWalletManager, wallet_i ``` **Description:** -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 - The returned pointer must be freed with `managed_account_collection_free` when no longer needed +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 **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 - The returned pointer must be freed with `managed_account_collection_free` when no longer needed +- `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 **Module:** `managed_account_collection` @@ -939,10 +936,10 @@ managed_wallet_get_account_count(manager: *const FFIWalletManager, wallet_id: *c ``` **Description:** -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 - The caller must ensure all pointers remain valid for the duration of this call +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 **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 - The caller must ensure all pointers remain valid for the duration of this call +- `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 **Module:** `managed_account` @@ -955,10 +952,10 @@ managed_wallet_get_address_pool_info(managed_wallet: *const FFIManagedWalletInfo ``` **Description:** -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 +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 **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 +- `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 **Module:** `address_pool` @@ -1115,10 +1112,10 @@ managed_wallet_get_utxos(managed_info: *const FFIManagedWalletInfo, utxos_out: * ``` **Description:** -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 - 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 +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 **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 - 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 +- `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 **Module:** `utxo` @@ -1147,10 +1144,10 @@ managed_wallet_mark_address_used(managed_wallet: *mut FFIManagedWalletInfo, addr ``` **Description:** -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 +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 **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 +- `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 **Module:** `address_pool` @@ -1163,26 +1160,26 @@ managed_wallet_set_gap_limit(managed_wallet: *mut FFIManagedWalletInfo, account_ ``` **Description:** -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 +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 **Safety:** -- `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - `error` must be a valid pointer to an FFIError +- `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - `error` must be a valid pointer to an FFIError or null **Module:** `address_pool` --- -#### `managed_wallet_synced_height` +#### `managed_wallet_last_processed_height` ```c -managed_wallet_synced_height(managed_wallet: *const FFIManagedWalletInfo, error: *mut FFIError,) -> c_uint +managed_wallet_last_processed_height(managed_wallet: *const FFIManagedWalletInfo, error: *mut FFIError,) -> c_uint ``` **Description:** -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 - The caller must ensure all pointers remain valid for the duration of this call +Get current last processed 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 **Safety:** -- `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call +- `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 **Module:** `managed_wallet` @@ -1339,10 +1336,10 @@ wallet_create_from_mnemonic(mnemonic: *const c_char, passphrase: *const c_char, ``` **Description:** -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 - 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 +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 **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 - 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 +- `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 **Module:** `wallet` @@ -1355,10 +1352,10 @@ wallet_create_from_mnemonic_with_options(mnemonic: *const c_char, passphrase: *c ``` **Description:** -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 - 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 +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 **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 - 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 +- `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 **Module:** `wallet` @@ -1371,10 +1368,10 @@ wallet_create_from_seed(seed: *const u8, seed_len: usize, network: FFINetwork, e ``` **Description:** -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 - The caller must ensure all pointers remain valid for the duration of this call +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 **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 - The caller must ensure all pointers remain valid for the duration of this call +- `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 **Module:** `wallet` @@ -1387,10 +1384,10 @@ wallet_create_from_seed_with_options(seed: *const u8, seed_len: usize, network: ``` **Description:** -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 - The caller must ensure all pointers remain valid for the duration of this call +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 **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 - The caller must ensure all pointers remain valid for the duration of this call +- `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 **Module:** `wallet` @@ -1403,10 +1400,10 @@ wallet_create_managed_wallet(wallet: *const FFIWallet, error: *mut FFIError,) -> ``` **Description:** -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 - The returned pointer must be freed with `managed_wallet_info_free` (or `ffi_managed_wallet_free` for compatibility) +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) **Safety:** -- `wallet` must be a valid pointer to an FFIWallet - `error` must be a valid pointer to an FFIError - The returned pointer must be freed with `managed_wallet_info_free` (or `ffi_managed_wallet_free` for compatibility) +- `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) **Module:** `transaction_checking` @@ -1419,10 +1416,10 @@ wallet_create_random(network: FFINetwork, error: *mut FFIError,) -> *mut FFIWall ``` **Description:** -Create a new random wallet (backward compatibility) # Safety - `error` must be a valid pointer to an FFIError structure - The caller must ensure the pointer remains valid for the duration of this call +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 **Safety:** -- `error` must be a valid pointer to an FFIError structure - The caller must ensure the pointer remains valid for the duration of this call +- `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 **Module:** `wallet` @@ -1435,10 +1432,10 @@ wallet_create_random_with_options(network: FFINetwork, account_options: *const F ``` **Description:** -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 - The caller must ensure all pointers remain valid for the duration of this call +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 **Safety:** -- `account_options` must be a valid pointer to FFIWalletAccountCreationOptions or null - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call +- `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 **Module:** `wallet` @@ -1595,10 +1592,10 @@ wallet_get_account_collection(wallet: *const FFIWallet, error: *mut FFIError,) - ``` **Description:** -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 - The returned pointer must be freed with `account_collection_free` when no longer needed +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 **Safety:** -- `wallet` must be a valid pointer to an FFIWallet instance - `error` must be a valid pointer to an FFIError structure - The returned pointer must be freed with `account_collection_free` when no longer needed +- `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 **Module:** `account_collection` @@ -1659,10 +1656,10 @@ wallet_get_id(wallet: *const FFIWallet, id_out: *mut u8, error: *mut FFIError,) ``` **Description:** -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 - The caller must ensure all pointers remain valid for the duration of this call +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 **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 - The caller must ensure all pointers remain valid for the duration of this call +- `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 **Module:** `wallet` @@ -1707,10 +1704,10 @@ wallet_get_xpub(wallet: *const FFIWallet, account_index: c_uint, error: *mut FFI ``` **Description:** -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 - 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 +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 **Safety:** -- `wallet` must be a valid pointer to an FFIWallet instance - `error` must be a valid pointer to an FFIError structure - 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 +- `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 **Module:** `wallet` @@ -1723,10 +1720,10 @@ wallet_has_mnemonic(wallet: *const FFIWallet, error: *mut FFIError,) -> bool ``` **Description:** -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 - The caller must ensure all pointers remain valid for the duration of this call +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 **Safety:** -- `wallet` must be a valid pointer to an FFIWallet instance - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call +- `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 **Module:** `wallet` @@ -1739,10 +1736,10 @@ wallet_is_watch_only(wallet: *const FFIWallet, error: *mut FFIError,) -> bool ``` **Description:** -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 - The caller must ensure all pointers remain valid for the duration of this call +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 **Safety:** -- `wallet` must be a valid pointer to an FFIWallet instance - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call +- `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 **Module:** `wallet` @@ -2189,10 +2186,10 @@ account_derive_extended_private_key_at(account: *const FFIAccount, master_xpriv: ``` **Description:** -Derive an extended private key from an account at a given index, using the provided master xpriv. Returns an opaque FFIExtendedPrivKey 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. - The caller must free the returned pointer with `extended_private_key_free`. +Derive an extended private key from an account at a given index, using the provided master xpriv. Returns an opaque FFIExtendedPrivKey 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`. **Safety:** -- `account` and `master_xpriv` must be valid, non-null pointers allocated by this library. - `error` must be a valid pointer to an FFIError. - The caller must free the returned pointer with `extended_private_key_free`. +- `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`. **Module:** `account_derivation` @@ -2205,10 +2202,10 @@ account_derive_extended_private_key_from_mnemonic(account: *const FFIAccount, mn ``` **Description:** -Derive an extended private key from a mnemonic + optional passphrase at the given index. Returns an opaque FFIExtendedPrivKey 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 +Derive an extended private key from a mnemonic + optional passphrase at the given index. Returns an opaque FFIExtendedPrivKey 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 **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 +- `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 **Module:** `account_derivation` @@ -2221,10 +2218,10 @@ account_derive_extended_private_key_from_seed(account: *const FFIAccount, seed: ``` **Description:** -Derive an extended private key from a raw seed buffer at the given index. Returns an opaque FFIExtendedPrivKey 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 +Derive an extended private key from a raw seed buffer at the given index. Returns an opaque FFIExtendedPrivKey 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 **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 +- `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 **Module:** `account_derivation` @@ -2237,10 +2234,10 @@ account_derive_private_key_as_wif_at(account: *const FFIAccount, master_xpriv: * ``` **Description:** -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 +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 **Safety:** -- `account` and `master_xpriv` must be valid pointers allocated by this library - `error` must be a valid pointer to an FFIError +- `account` and `master_xpriv` must be valid pointers allocated by this library - `error` must be a valid pointer to an FFIError or null **Module:** `account_derivation` @@ -2253,10 +2250,10 @@ account_derive_private_key_at(account: *const FFIAccount, master_xpriv: *const F ``` **Description:** -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 +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 **Safety:** -- `account` and `master_xpriv` must be valid pointers allocated by this library - `error` must be a valid pointer to an FFIError +- `account` and `master_xpriv` must be valid pointers allocated by this library - `error` must be a valid pointer to an FFIError or null **Module:** `account_derivation` @@ -2269,10 +2266,10 @@ account_derive_private_key_from_mnemonic(account: *const FFIAccount, mnemonic: * ``` **Description:** -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 +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 **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 +- `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 **Module:** `account_derivation` @@ -2285,10 +2282,10 @@ account_derive_private_key_from_seed(account: *const FFIAccount, seed: *const u8 ``` **Description:** -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 +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 **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 +- `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 **Module:** `account_derivation` @@ -2451,10 +2448,7 @@ derivation_bip44_account_path(network: FFINetwork, account_index: c_uint, path_o ``` **Description:** -Derive a BIP44 account path (m/44'/5'/account') # Safety `path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. - -**Safety:** -`path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. +Derive a BIP44 account path (m/44'/5'/account') **Module:** `derivation` @@ -3515,10 +3509,10 @@ address_pool_get_address_at_index(pool: *const FFIAddressPool, index: u32, error ``` **Description:** -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 - The returned FFIAddressInfo must be freed using `address_info_free` +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` **Safety:** -- `pool` must be a valid pointer to an FFIAddressPool - `error` must be a valid pointer to an FFIError - The returned FFIAddressInfo must be freed using `address_info_free` +- `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` **Module:** `address_pool` @@ -3531,10 +3525,10 @@ address_pool_get_addresses_in_range(pool: *const FFIAddressPool, start_index: u3 ``` **Description:** -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 - The returned array must be freed using `address_info_array_free` +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` **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 - The returned array must be freed using `address_info_array_free` +- `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` **Module:** `address_pool` @@ -3645,10 +3639,10 @@ transaction_classify(tx_bytes: *const u8, tx_len: usize, error: *mut FFIError,) ``` **Description:** -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 - The returned string must be freed by the caller +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 **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 - The returned string must be freed by the caller +- `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 **Module:** `transaction_checking` @@ -3800,14 +3794,14 @@ Free UTXO array # Safety - `utxos` must be a valid pointer to an array of FFIU #### `bip38_decrypt_private_key` ```c -bip38_decrypt_private_key(_encrypted_key: *const c_char, _passphrase: *const c_char, error: *mut FFIError,) -> *mut c_char +bip38_decrypt_private_key(encrypted_key: *const c_char, passphrase: *const c_char, error: *mut FFIError,) -> *mut c_char ``` **Description:** -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 +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 **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 +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 **Module:** `bip38` @@ -3816,14 +3810,14 @@ This function is unsafe because it dereferences raw pointers: - `encrypted_key` #### `bip38_encrypt_private_key` ```c -bip38_encrypt_private_key(_private_key: *const c_char, _passphrase: *const c_char, error: *mut FFIError,) -> *mut c_char +bip38_encrypt_private_key(private_key: *const c_char, passphrase: *const c_char, error: *mut FFIError,) -> *mut c_char ``` **Description:** -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 +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 **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 +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 **Module:** `bip38` @@ -3836,10 +3830,10 @@ derivation_derive_private_key_from_seed(seed: *const u8, seed_len: usize, path: ``` **Description:** -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 - The caller must ensure all pointers remain valid for the duration of this call +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 **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 - The caller must ensure all pointers remain valid for the duration of this call +- `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 **Module:** `derivation` @@ -3852,10 +3846,10 @@ derivation_new_master_key(seed: *const u8, seed_len: usize, network: FFINetwork, ``` **Description:** -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 - The caller must ensure the seed pointer remains valid for the duration of this call +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 **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 - The caller must ensure the seed pointer remains valid for the duration of this call +- `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 **Module:** `derivation` @@ -3896,7 +3890,7 @@ Get the private key from an extended private key Extracts the non-extended priv #### `extended_private_key_to_string` ```c -extended_private_key_to_string(key: *const FFIExtendedPrivKey, _network: FFINetwork, error: *mut FFIError,) -> *mut c_char +extended_private_key_to_string(key: *const FFIExtendedPrivKey, network: FFINetwork, error: *mut FFIError,) -> *mut c_char ``` **Description:** @@ -3944,7 +3938,7 @@ Get the public key from an extended public key Extracts the non-extended public #### `extended_public_key_to_string` ```c -extended_public_key_to_string(key: *const FFIExtendedPubKey, _network: FFINetwork, error: *mut FFIError,) -> *mut c_char +extended_public_key_to_string(key: *const FFIExtendedPubKey, network: FFINetwork, error: *mut FFIError,) -> *mut c_char ``` **Description:** @@ -4042,14 +4036,11 @@ Free a mnemonic string # Safety - `mnemonic` must be a valid pointer created b #### `mnemonic_generate` ```c -mnemonic_generate(word_count: c_uint, error: *mut FFIError,) -> *mut c_char +mnemonic_generate(word_count: c_uint, error: *mut FFIError) -> *mut c_char ``` **Description:** -Generate a new mnemonic with specified word count (12, 15, 18, 21, or 24) # Safety `error` must be a valid pointer to an `FFIError`. The returned string must be freed with `mnemonic_free`. - -**Safety:** -`error` must be a valid pointer to an `FFIError`. The returned string must be freed with `mnemonic_free`. +Generate a new mnemonic with specified word count (12, 15, 18, 21, or 24) **Module:** `mnemonic` @@ -4062,10 +4053,7 @@ mnemonic_generate_with_language(word_count: c_uint, language: FFILanguage, error ``` **Description:** -Generate a new mnemonic with specified language and word count # Safety `error` must be a valid pointer to an `FFIError`. The returned string must be freed with `mnemonic_free`. - -**Safety:** -`error` must be a valid pointer to an `FFIError`. The returned string must be freed with `mnemonic_free`. +Generate a new mnemonic with specified language and word count **Module:** `mnemonic` @@ -4128,10 +4116,7 @@ derivation_bip44_payment_path(network: FFINetwork, account_index: c_uint, is_cha ``` **Description:** -Derive a BIP44 payment path (m/44'/5'/account'/change/index) # Safety `path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. - -**Safety:** -`path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. +Derive a BIP44 payment path (m/44'/5'/account'/change/index) **Module:** `derivation` @@ -4144,10 +4129,7 @@ derivation_coinjoin_path(network: FFINetwork, account_index: c_uint, path_out: * ``` **Description:** -Derive CoinJoin path (m/9'/5'/4'/account') # Safety `path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. - -**Safety:** -`path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. +Derive CoinJoin path (m/9'/5'/4'/account') **Module:** `derivation` @@ -4160,10 +4142,7 @@ derivation_identity_authentication_path(network: FFINetwork, identity_index: c_u ``` **Description:** -Derive identity authentication path (m/9'/5'/5'/0'/identity_index'/key_index') # Safety `path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. - -**Safety:** -`path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. +Derive identity authentication path (m/9'/5'/5'/0'/identity_index'/key_index') **Module:** `derivation` @@ -4176,10 +4155,7 @@ derivation_identity_registration_path(network: FFINetwork, identity_index: c_uin ``` **Description:** -Derive identity registration path (m/9'/5'/5'/1'/index') # Safety `path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. - -**Safety:** -`path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. +Derive identity registration path (m/9'/5'/5'/1'/index') **Module:** `derivation` @@ -4192,10 +4168,7 @@ derivation_identity_topup_path(network: FFINetwork, identity_index: c_uint, topu ``` **Description:** -Derive identity top-up path (m/9'/5'/5'/2'/identity_index'/top_up_index') # Safety `path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. - -**Safety:** -`path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. +Derive identity top-up path (m/9'/5'/5'/2'/identity_index'/top_up_index') **Module:** `derivation` diff --git a/key-wallet-ffi/src/managed_wallet.rs b/key-wallet-ffi/src/managed_wallet.rs index 05e2c1062..47fc2dffb 100644 --- a/key-wallet-ffi/src/managed_wallet.rs +++ b/key-wallet-ffi/src/managed_wallet.rs @@ -453,7 +453,7 @@ pub unsafe extern "C" fn managed_wallet_get_balance( true } -/// Get current synced height from wallet info +/// Get current last processed height from wallet info /// /// # Safety /// @@ -461,12 +461,12 @@ pub unsafe extern "C" fn managed_wallet_get_balance( /// - `error` must be a valid pointer to an FFIError structure /// - The caller must ensure all pointers remain valid for the duration of this call #[no_mangle] -pub unsafe extern "C" fn managed_wallet_synced_height( +pub unsafe extern "C" fn managed_wallet_last_processed_height( managed_wallet: *const FFIManagedWalletInfo, error: *mut FFIError, ) -> c_uint { let managed_wallet = deref_ptr!(managed_wallet, error); - managed_wallet.inner().synced_height() + managed_wallet.inner().last_processed_height() } /// Free managed wallet info diff --git a/key-wallet-ffi/src/transaction.rs b/key-wallet-ffi/src/transaction.rs index cd8917155..c58a743b5 100644 --- a/key-wallet-ffi/src/transaction.rs +++ b/key-wallet-ffi/src/transaction.rs @@ -246,7 +246,7 @@ pub unsafe extern "C" fn wallet_build_and_sign_transaction( let mut tx_builder_with_inputs = match tx_builder.select_inputs( &utxos, SelectionStrategy::BranchAndBound, - managed_wallet.synced_height(), + managed_wallet.last_processed_height(), |utxo| { // Look up the derivation path for this UTXO's address let path = address_to_path.get(&utxo.address)?; diff --git a/key-wallet-ffi/src/utxo.rs b/key-wallet-ffi/src/utxo.rs index 5150adb7a..3ecb1585b 100644 --- a/key-wallet-ffi/src/utxo.rs +++ b/key-wallet-ffi/src/utxo.rs @@ -117,7 +117,7 @@ pub unsafe extern "C" fn managed_wallet_get_utxos( // Get script bytes let script_bytes = utxo.txout.script_pubkey.as_bytes().to_vec(); - let current_height = managed_info.inner().synced_height(); + let current_height = managed_info.inner().last_processed_height(); let confirmations = utxo.confirmations(current_height); let ffi_utxo = FFIUTXO::new( diff --git a/key-wallet-ffi/src/utxo_tests.rs b/key-wallet-ffi/src/utxo_tests.rs index d6cba5c58..6b8fc35cc 100644 --- a/key-wallet-ffi/src/utxo_tests.rs +++ b/key-wallet-ffi/src/utxo_tests.rs @@ -233,7 +233,7 @@ mod utxo_tests { managed_info.accounts.insert(bip44_account).unwrap(); let ffi_managed_info = Box::into_raw(Box::new(FFIManagedWalletInfo::new(managed_info))); - unsafe { (*ffi_managed_info).inner_mut() }.update_synced_height(300); + unsafe { (*ffi_managed_info).inner_mut() }.update_last_processed_height(300); let result = unsafe { managed_wallet_get_utxos(&*ffi_managed_info, &mut utxos_out, &mut count_out, error) }; diff --git a/key-wallet-ffi/src/wallet_manager.rs b/key-wallet-ffi/src/wallet_manager.rs index 2cb4cbc92..adfcd5a55 100644 --- a/key-wallet-ffi/src/wallet_manager.rs +++ b/key-wallet-ffi/src/wallet_manager.rs @@ -570,7 +570,7 @@ pub unsafe extern "C" fn wallet_manager_current_height( let manager_ref = deref_ptr!(manager, error); manager_ref.runtime.block_on(async { let manager_guard = manager_ref.manager.read().await; - manager_guard.synced_height() + manager_guard.last_processed_height() }) } diff --git a/key-wallet-ffi/src/wallet_manager_tests.rs b/key-wallet-ffi/src/wallet_manager_tests.rs index 5c1ba66a5..b26eb2b3f 100644 --- a/key-wallet-ffi/src/wallet_manager_tests.rs +++ b/key-wallet-ffi/src/wallet_manager_tests.rs @@ -448,7 +448,7 @@ mod tests { let manager_ref = &*manager; manager_ref.runtime.block_on(async { let mut manager_guard = manager_ref.manager.write().await; - manager_guard.update_synced_height(new_height); + manager_guard.update_last_processed_height(new_height); }); } diff --git a/key-wallet-manager/examples/wallet_creation.rs b/key-wallet-manager/examples/wallet_creation.rs index 4529f5bb7..a80d3242e 100644 --- a/key-wallet-manager/examples/wallet_creation.rs +++ b/key-wallet-manager/examples/wallet_creation.rs @@ -142,11 +142,11 @@ fn main() { // Example 7: Block height tracking println!("\n7. Block height tracking..."); - println!(" Current height (Testnet): {:?}", manager.synced_height()); + println!(" Current height (Testnet): {:?}", manager.last_processed_height()); // Update height - manager.update_synced_height(850_000); - println!(" Updated height to: {:?}", manager.synced_height()); + manager.update_last_processed_height(850_000); + println!(" Updated height to: {:?}", manager.last_processed_height()); println!("\n=== Summary ==="); println!("Total wallets created: {}", manager.wallet_count()); diff --git a/key-wallet-manager/src/lib.rs b/key-wallet-manager/src/lib.rs index ccb293edd..b5c7b9e88 100644 --- a/key-wallet-manager/src/lib.rs +++ b/key-wallet-manager/src/lib.rs @@ -91,7 +91,7 @@ pub struct WalletManager { /// Network the managed wallets are used for network: Network, /// Last fully processed block height. - synced_height: CoreBlockHeight, + last_processed_height: CoreBlockHeight, /// Height at which filter scanning was last committed. filter_committed_height: CoreBlockHeight, /// Immutable wallets indexed by wallet ID @@ -111,7 +111,7 @@ impl WalletManager { pub fn new(network: Network) -> Self { Self { network, - synced_height: 0, + last_processed_height: 0, filter_committed_height: 0, wallets: BTreeMap::new(), wallet_infos: BTreeMap::new(), @@ -304,7 +304,7 @@ impl WalletManager { // Create managed wallet info let mut managed_info = T::from_wallet(&wallet); - managed_info.set_birth_height(self.synced_height); + managed_info.set_birth_height(self.last_processed_height); managed_info.set_first_loaded_at(current_timestamp()); self.wallets.insert(wallet_id, wallet); @@ -345,7 +345,7 @@ impl WalletManager { // Create managed wallet info let mut managed_info = T::from_wallet(&wallet); - managed_info.set_birth_height(self.synced_height); + managed_info.set_birth_height(self.last_processed_height); managed_info.set_first_loaded_at(current_timestamp()); self.wallets.insert(wallet_id, wallet); @@ -393,7 +393,7 @@ impl WalletManager { // Create managed wallet info let mut managed_info = T::from_wallet(&wallet); - managed_info.set_birth_height(self.synced_height); + managed_info.set_birth_height(self.last_processed_height); managed_info.set_first_loaded_at(current_timestamp()); self.wallets.insert(wallet_id, wallet); @@ -438,7 +438,7 @@ impl WalletManager { let mut managed_info = T::from_wallet(&wallet); // Use the current height as the birth height since we don't know when it was originally created - managed_info.set_birth_height(self.synced_height); + managed_info.set_birth_height(self.last_processed_height); managed_info.set_first_loaded_at(current_timestamp()); self.wallets.insert(wallet_id, wallet); diff --git a/key-wallet-manager/src/process_block.rs b/key-wallet-manager/src/process_block.rs index 2e5d27cb2..e7b3cf770 100644 --- a/key-wallet-manager/src/process_block.rs +++ b/key-wallet-manager/src/process_block.rs @@ -37,7 +37,7 @@ impl WalletInterface for WalletM result.new_addresses.extend(check_result.new_addresses); } - self.update_synced_height(height); + self.update_last_processed_height(height); result } @@ -97,17 +97,17 @@ impl WalletInterface for WalletM self.wallet_infos.values().map(|info| info.birth_height()).min().unwrap_or(0) } - fn synced_height(&self) -> CoreBlockHeight { - self.synced_height + fn last_processed_height(&self) -> CoreBlockHeight { + self.last_processed_height } - fn update_synced_height(&mut self, height: CoreBlockHeight) { - self.synced_height = height; + fn update_last_processed_height(&mut self, height: CoreBlockHeight) { + self.last_processed_height = height; let snapshot = self.snapshot_balances(); for (_wallet_id, info) in self.wallet_infos.iter_mut() { - info.update_synced_height(height); + info.update_last_processed_height(height); } self.emit_balance_changes(&snapshot); @@ -119,8 +119,8 @@ impl WalletInterface for WalletM fn update_filter_committed_height(&mut self, height: CoreBlockHeight) { self.filter_committed_height = height; - if height > self.synced_height { - self.update_synced_height(height); + if height > self.last_processed_height { + self.update_last_processed_height(height); } } @@ -216,19 +216,19 @@ mod tests { } #[tokio::test] - async fn test_synced_height() { + async fn test_last_processed_height() { let mut manager: WalletManager = WalletManager::new(Network::Testnet); // Initial state - assert_eq!(manager.synced_height(), 0); - // Inrease synced height - manager.update_synced_height(1000); - assert_eq!(manager.synced_height(), 1000); - //Increase synced height again - manager.update_synced_height(5000); - assert_eq!(manager.synced_height(), 5000); - // Decrease synced height - manager.update_synced_height(10); - assert_eq!(manager.synced_height(), 10); + assert_eq!(manager.last_processed_height(), 0); + // Increase last processed height + manager.update_last_processed_height(1000); + assert_eq!(manager.last_processed_height(), 1000); + // Increase last processed height again + manager.update_last_processed_height(5000); + assert_eq!(manager.last_processed_height(), 5000); + // Decrease last processed height + manager.update_last_processed_height(10); + assert_eq!(manager.last_processed_height(), 10); } #[tokio::test] @@ -386,9 +386,9 @@ mod tests { assert_eq!(manager.monitor_revision(), expected_rev, "after get_change_address"); } - // update_synced_height does NOT bump - manager.update_synced_height(1000); - assert_eq!(manager.monitor_revision(), expected_rev, "after update_synced_height"); + // update_last_processed_height does NOT bump + manager.update_last_processed_height(1000); + assert_eq!(manager.monitor_revision(), expected_rev, "after update_last_processed_height"); // process_mempool_transaction bumps from UTXO changes and possibly // new addresses generated via gap limit maintenance diff --git a/key-wallet-manager/src/test_utils/mock_wallet.rs b/key-wallet-manager/src/test_utils/mock_wallet.rs index d17cb1ce3..180e064ac 100644 --- a/key-wallet-manager/src/test_utils/mock_wallet.rs +++ b/key-wallet-manager/src/test_utils/mock_wallet.rs @@ -12,7 +12,7 @@ type InstantLockCaptures = Arc)>>>; pub struct MockWallet { processed_blocks: Arc>>, processed_transactions: Arc>>, - synced_height: CoreBlockHeight, + last_processed_height: CoreBlockHeight, event_sender: broadcast::Sender, /// When true, process_mempool_transaction returns is_relevant=true. mempool_relevant: bool, @@ -47,7 +47,7 @@ impl MockWallet { Self { processed_blocks: Arc::new(Mutex::new(Vec::new())), processed_transactions: Arc::new(Mutex::new(Vec::new())), - synced_height: 0, + last_processed_height: 0, event_sender, mempool_relevant: false, addresses: Vec::new(), @@ -156,12 +156,12 @@ impl WalletInterface for MockWallet { self.outpoints.clone() } - fn synced_height(&self) -> CoreBlockHeight { - self.synced_height + fn last_processed_height(&self) -> CoreBlockHeight { + self.last_processed_height } - fn update_synced_height(&mut self, height: CoreBlockHeight) { - self.synced_height = height; + fn update_last_processed_height(&mut self, height: CoreBlockHeight) { + self.last_processed_height = height; } fn monitor_revision(&self) -> u64 { @@ -189,7 +189,7 @@ impl WalletInterface for MockWallet { /// Mock wallet that returns false for filter checks pub struct NonMatchingMockWallet { - synced_height: CoreBlockHeight, + last_processed_height: CoreBlockHeight, event_sender: broadcast::Sender, } @@ -203,7 +203,7 @@ impl NonMatchingMockWallet { pub fn new() -> Self { let (event_sender, _) = broadcast::channel(16); Self { - synced_height: 0, + last_processed_height: 0, event_sender, } } @@ -231,12 +231,12 @@ impl WalletInterface for NonMatchingMockWallet { Vec::new() } - fn synced_height(&self) -> CoreBlockHeight { - self.synced_height + fn last_processed_height(&self) -> CoreBlockHeight { + self.last_processed_height } - fn update_synced_height(&mut self, height: CoreBlockHeight) { - self.synced_height = height; + fn update_last_processed_height(&mut self, height: CoreBlockHeight) { + self.last_processed_height = height; } fn subscribe_events(&self) -> broadcast::Receiver { diff --git a/key-wallet-manager/src/wallet_interface.rs b/key-wallet-manager/src/wallet_interface.rs index 85a066368..44c815ac0 100644 --- a/key-wallet-manager/src/wallet_interface.rs +++ b/key-wallet-manager/src/wallet_interface.rs @@ -86,23 +86,23 @@ pub trait WalletInterface: Send + Sync + 'static { } /// Return the last fully processed height of the wallet. - fn synced_height(&self) -> CoreBlockHeight; + fn last_processed_height(&self) -> CoreBlockHeight; - /// Update the wallet's synced height. This also triggers balance updates. - fn update_synced_height(&mut self, height: CoreBlockHeight); + /// Update the wallet's last processed height. This also triggers balance updates. + fn update_last_processed_height(&mut self, height: CoreBlockHeight); /// Return the height at which filter scanning was last committed. - /// Defaults to `synced_height()` for implementations that don't separate these concepts. - // TODO: This can probably somehow be combined with synced_height(). + /// Defaults to `last_processed_height()` for implementations that don't separate these concepts. + // TODO: This can probably somehow be combined with last_processed_height(). fn filter_committed_height(&self) -> CoreBlockHeight { - self.synced_height() + self.last_processed_height() } /// Update the filter committed height. Call when a height is fully processed /// (including any rescans for newly discovered addresses). fn update_filter_committed_height(&mut self, height: CoreBlockHeight) { - if height > self.synced_height() { - self.update_synced_height(height); + if height > self.last_processed_height() { + self.update_last_processed_height(height); } } diff --git a/key-wallet-manager/tests/integration_test.rs b/key-wallet-manager/tests/integration_test.rs index e48674469..6a0360380 100644 --- a/key-wallet-manager/tests/integration_test.rs +++ b/key-wallet-manager/tests/integration_test.rs @@ -17,7 +17,7 @@ fn test_wallet_manager_creation() { let manager = WalletManager::::new(Network::Testnet); // WalletManager::new returns Self, not Result - assert_eq!(manager.synced_height(), 0); + assert_eq!(manager.last_processed_height(), 0); assert_eq!(manager.wallet_count(), 0); // No wallets created yet assert_eq!(manager.monitor_revision(), 0); } @@ -163,11 +163,11 @@ fn test_block_height_tracking() { let mut manager = WalletManager::::new(Network::Testnet); // Initial state - assert_eq!(manager.synced_height(), 0); + assert_eq!(manager.last_processed_height(), 0); // Set height before adding wallets - manager.update_synced_height(1000); - assert_eq!(manager.synced_height(), 1000); + manager.update_last_processed_height(1000); + assert_eq!(manager.last_processed_height(), 1000); let mnemonic1 = Mnemonic::generate(12, Language::English).unwrap(); let wallet_id1 = manager @@ -191,46 +191,46 @@ fn test_block_height_tracking() { assert_eq!(manager.wallet_count(), 2); - // Verify both wallets have synced_height of 0 initially + // Verify both wallets have last_processed_height of 0 initially for wallet_info in manager.get_all_wallet_infos().values() { - assert_eq!(wallet_info.synced_height(), 0); + assert_eq!(wallet_info.last_processed_height(), 0); } // Update height - should propagate to all wallets - manager.update_synced_height(12345); - assert_eq!(manager.synced_height(), 12345); + manager.update_last_processed_height(12345); + assert_eq!(manager.last_processed_height(), 12345); // Verify all wallets got updated let wallet_info1 = manager.get_wallet_info(&wallet_id1).unwrap(); let wallet_info2 = manager.get_wallet_info(&wallet_id2).unwrap(); - assert_eq!(wallet_info1.synced_height(), 12345); - assert_eq!(wallet_info2.synced_height(), 12345); + assert_eq!(wallet_info1.last_processed_height(), 12345); + assert_eq!(wallet_info2.last_processed_height(), 12345); // Update again - verify subsequent updates work - manager.update_synced_height(20000); - assert_eq!(manager.synced_height(), 20000); + manager.update_last_processed_height(20000); + assert_eq!(manager.last_processed_height(), 20000); for wallet_info in manager.get_all_wallet_infos().values() { - assert_eq!(wallet_info.synced_height(), 20000); + assert_eq!(wallet_info.last_processed_height(), 20000); } // Update wallets individually to different heights let wallet_info1 = manager.get_wallet_info_mut(&wallet_id1).unwrap(); - wallet_info1.update_synced_height(30000); + wallet_info1.update_last_processed_height(30000); let wallet_info2 = manager.get_wallet_info_mut(&wallet_id2).unwrap(); - wallet_info2.update_synced_height(25000); + wallet_info2.update_last_processed_height(25000); - // Verify each wallet has its own synced_height + // Verify each wallet has its own last_processed_height let wallet_info1 = manager.get_wallet_info(&wallet_id1).unwrap(); let wallet_info2 = manager.get_wallet_info(&wallet_id2).unwrap(); - assert_eq!(wallet_info1.synced_height(), 30000); - assert_eq!(wallet_info2.synced_height(), 25000); + assert_eq!(wallet_info1.last_processed_height(), 30000); + assert_eq!(wallet_info2.last_processed_height(), 25000); // Manager update_height still syncs all wallets - manager.update_synced_height(40000); + manager.update_last_processed_height(40000); let wallet_info1 = manager.get_wallet_info(&wallet_id1).unwrap(); let wallet_info2 = manager.get_wallet_info(&wallet_id2).unwrap(); - assert_eq!(wallet_info1.synced_height(), 40000); - assert_eq!(wallet_info2.synced_height(), 40000); + assert_eq!(wallet_info1.last_processed_height(), 40000); + assert_eq!(wallet_info2.last_processed_height(), 40000); } diff --git a/key-wallet-manager/tests/spv_integration_tests.rs b/key-wallet-manager/tests/spv_integration_tests.rs index ddcffc29a..71b3bbfab 100644 --- a/key-wallet-manager/tests/spv_integration_tests.rs +++ b/key-wallet-manager/tests/spv_integration_tests.rs @@ -69,12 +69,17 @@ async fn test_block_processing_result_empty() { } fn assert_wallet_heights(manager: &WalletManager, expected_height: u32) { - assert_eq!(manager.synced_height(), expected_height, "height should be {}", expected_height); + assert_eq!( + manager.last_processed_height(), + expected_height, + "height should be {}", + expected_height + ); for wallet_info in manager.get_all_wallet_infos().values() { assert_eq!( - wallet_info.synced_height(), + wallet_info.last_processed_height(), expected_height, - "synced_height should be {}", + "last_processed_height should be {}", expected_height ); } diff --git a/key-wallet/src/managed_account/mod.rs b/key-wallet/src/managed_account/mod.rs index c8064dae1..6ce168c3f 100644 --- a/key-wallet/src/managed_account/mod.rs +++ b/key-wallet/src/managed_account/mod.rs @@ -555,12 +555,15 @@ impl ManagedCoreAccount { } /// Return the UTXOs of this account for which - /// [`Utxo::is_spendable`] holds at `synced_height`. See that method + /// [`Utxo::is_spendable`] holds at `last_processed_height`. See that method /// for the exact policy. Call this per-account rather than /// aggregating across the wallet, since spendability is /// account-type specific. - pub fn spendable_utxos(&self, synced_height: u32) -> BTreeSet<&Utxo> { - self.utxos.values().filter(|utxo| utxo.is_spendable(synced_height)).collect() + pub fn spendable_utxos(&self, last_processed_height: u32) -> BTreeSet<&Utxo> { + self.utxos + .values() + .filter(|utxo| utxo.is_spendable(last_processed_height)) + .collect() } /// Update the account balance. @@ -569,7 +572,7 @@ impl ManagedCoreAccount { /// (in a block or InstantSend-locked) or the `unconfirmed` bucket /// (mempool only). Both are spendable per [`Utxo::is_spendable`]; /// the split is only for display. - pub fn update_balance(&mut self, synced_height: u32) { + pub fn update_balance(&mut self, last_processed_height: u32) { let mut confirmed = 0; let mut unconfirmed = 0; let mut immature = 0; @@ -578,7 +581,7 @@ impl ManagedCoreAccount { let value = utxo.txout.value; if utxo.is_locked { locked += value; - } else if !utxo.is_mature(synced_height) { + } else if !utxo.is_mature(last_processed_height) { immature += value; } else if utxo.is_confirmed || utxo.is_instantlocked { confirmed += value; diff --git a/key-wallet/src/tests/balance_tests.rs b/key-wallet/src/tests/balance_tests.rs index 4d6ed746c..05706879b 100644 --- a/key-wallet/src/tests/balance_tests.rs +++ b/key-wallet/src/tests/balance_tests.rs @@ -22,7 +22,7 @@ fn test_balance_with_mixed_utxo_types() { wallet_info.accounts.insert(account).unwrap(); assert_eq!(wallet_info.balance(), WalletCoreBalance::default()); - wallet_info.update_synced_height(1100); + wallet_info.update_last_processed_height(1100); let expected = WalletCoreBalance::new(10_100_000, 0, 20_000_000, 0); assert_eq!(wallet_info.balance(), expected); } @@ -39,12 +39,12 @@ fn test_coinbase_maturity_boundary() { assert_eq!(wallet_info.balance(), WalletCoreBalance::default()); // 99 confirmations: immature - wallet_info.update_synced_height(1099); + wallet_info.update_last_processed_height(1099); let expected_immature = WalletCoreBalance::new(0, 0, 50_000_000, 0); assert_eq!(wallet_info.balance(), expected_immature); // 100 confirmations: mature - wallet_info.update_synced_height(1100); + wallet_info.update_last_processed_height(1100); let expected_mature = WalletCoreBalance::new(50_000_000, 0, 0, 0); assert_eq!(wallet_info.balance(), expected_mature); } @@ -60,7 +60,7 @@ fn test_locked_utxos_in_locked_balance() { wallet_info.accounts.insert(account).unwrap(); assert_eq!(wallet_info.balance(), WalletCoreBalance::default()); - wallet_info.update_synced_height(1100); + wallet_info.update_last_processed_height(1100); let expected = WalletCoreBalance::new(0, 0, 0, 100_000); assert_eq!(wallet_info.balance(), expected); } @@ -75,7 +75,7 @@ fn test_unconfirmed_utxos_in_unconfirmed_balance() { wallet_info.accounts.insert(account).unwrap(); assert_eq!(wallet_info.balance(), WalletCoreBalance::default()); - wallet_info.update_synced_height(1100); + wallet_info.update_last_processed_height(1100); let expected = WalletCoreBalance::new(0, 100_000, 0, 0); assert_eq!(wallet_info.balance(), expected); } diff --git a/key-wallet/src/transaction_checking/wallet_checker.rs b/key-wallet/src/transaction_checking/wallet_checker.rs index 05a8625a1..391df1ae6 100644 --- a/key-wallet/src/transaction_checking/wallet_checker.rs +++ b/key-wallet/src/transaction_checking/wallet_checker.rs @@ -26,7 +26,7 @@ pub trait WalletTransactionChecker { /// /// If `update_balance` is true, refreshes the cached wallet balance after mutations. /// Callers that batch multiple transactions (e.g. block processing) can pass `false` - /// and refresh once at the end via `update_synced_height`. + /// and refresh once at the end via `update_last_processed_height`. /// /// The context parameter indicates where the transaction comes from (mempool, block, etc.) /// @@ -400,8 +400,8 @@ mod tests { let result = managed_wallet .check_core_transaction(&coinbase_tx, context, &mut wallet, true, true) .await; - // Set synced_height to block where coinbase was received to trigger balance updates. - managed_wallet.update_synced_height(block_height); + // Set last_processed_height to block where coinbase was received to trigger balance updates. + managed_wallet.update_last_processed_height(block_height); // Should be relevant assert!(result.is_relevant); @@ -428,12 +428,12 @@ mod tests { assert_eq!(managed_wallet.balance().immature(), 5_000_000_000); // Spendable UTXOs should be empty (coinbase not mature) - let synced_height = managed_wallet.synced_height(); + let last_processed_height = managed_wallet.last_processed_height(); assert!( managed_wallet .first_bip44_managed_account() .expect("Should have managed account") - .spendable_utxos(synced_height) + .spendable_utxos(last_processed_height) .is_empty(), "Coinbase UTXO should not be spendable until mature" ); @@ -560,8 +560,8 @@ mod tests { let result = managed_wallet .check_core_transaction(&coinbase_tx, context, &mut wallet, true, true) .await; - // Set synced_height to block where coinbase was received to trigger balance updates. - managed_wallet.update_synced_height(block_height); + // Set last_processed_height to block where coinbase was received to trigger balance updates. + managed_wallet.update_last_processed_height(block_height); // Should be relevant assert!(result.is_relevant); @@ -587,19 +587,19 @@ mod tests { assert_eq!(managed_wallet.balance().immature(), 5_000_000_000); // Spendable UTXOs should be empty (coinbase not mature yet) - let synced_height = managed_wallet.synced_height(); + let last_processed_height = managed_wallet.last_processed_height(); assert!( managed_wallet .first_bip44_managed_account() .expect("Should have managed account") - .spendable_utxos(synced_height) + .spendable_utxos(last_processed_height) .is_empty(), "No spendable UTXOs while coinbase is immature" ); // Now advance the chain height past maturity (100 blocks) let mature_height = block_height + 100; - managed_wallet.update_synced_height(mature_height); + managed_wallet.update_last_processed_height(mature_height); let managed_account = managed_wallet.first_bip44_managed_account().expect("Should have managed account"); @@ -617,11 +617,11 @@ mod tests { assert_eq!(immature_balance, 0, "Immature balance should be zero after maturity"); // Spendable UTXOs should now contain the matured coinbase - let synced_height = managed_wallet.synced_height(); + let last_processed_height = managed_wallet.last_processed_height(); let spendable = managed_wallet .first_bip44_managed_account() .expect("Should have managed account") - .spendable_utxos(synced_height); + .spendable_utxos(last_processed_height); assert_eq!(spendable.len(), 1, "Should have one spendable UTXO after maturity"); } diff --git a/key-wallet/src/wallet/managed_wallet_info/asset_lock_builder.rs b/key-wallet/src/wallet/managed_wallet_info/asset_lock_builder.rs index 1ebeaabda..8dc0b1a9c 100644 --- a/key-wallet/src/wallet/managed_wallet_info/asset_lock_builder.rs +++ b/key-wallet/src/wallet/managed_wallet_info/asset_lock_builder.rs @@ -238,7 +238,7 @@ impl ManagedWalletInfo { .and_then(|account| account.next_change_address(xpub.as_ref(), true).ok()) .ok_or(AssetLockError::NoChangeAddress)?; - let synced_height = self.synced_height(); + let last_processed_height = self.last_processed_height(); // Separate credit outputs from funding specs let credit_outputs: Vec = @@ -271,7 +271,7 @@ impl ManagedWalletInfo { let tx_builder_with_inputs = tx_builder.select_inputs( &utxos, SelectionStrategy::BranchAndBound, - synced_height, + last_processed_height, |utxo| { let path = address_to_path.get(&utxo.address)?; let root_ext_priv = root_xpriv.to_extended_priv_key(network); @@ -373,7 +373,7 @@ impl ManagedWalletInfo { .and_then(|account| account.next_change_address(xpub.as_ref(), true).ok()) .ok_or(AssetLockError::NoChangeAddress)?; - let synced_height = self.synced_height(); + let last_processed_height = self.last_processed_height(); let credit_outputs: Vec = credit_output_fundings.iter().map(|f| f.output.clone()).collect(); @@ -398,7 +398,7 @@ impl ManagedWalletInfo { let tx_builder_with_inputs = tx_builder.select_inputs( &utxos, SelectionStrategy::BranchAndBound, - synced_height, + last_processed_height, |_utxo| None, )?; @@ -789,7 +789,7 @@ mod tests { .unwrap() .utxos .insert(utxo.outpoint, utxo); - info.update_synced_height(1100); + info.update_last_processed_height(1100); let signer = InMemorySigner { root, diff --git a/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs b/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs index 33f7aba6c..4ce77dcea 100644 --- a/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs +++ b/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs @@ -65,6 +65,9 @@ pub trait WalletInfoInterface: Sized + WalletTransactionChecker + ManagedAccount /// Get all UTXOs for the wallet fn utxos(&self) -> BTreeSet<&Utxo>; + /// Get spendable UTXOs (confirmed and not locked) + fn get_spendable_utxos(&self) -> BTreeSet<&Utxo>; + /// Get the wallet balance fn balance(&self) -> WalletCoreBalance; @@ -84,11 +87,11 @@ pub trait WalletInfoInterface: Sized + WalletTransactionChecker + ManagedAccount fn immature_transactions(&self) -> Vec; /// Return the last fully processed height of the wallet. - fn synced_height(&self) -> CoreBlockHeight; + fn last_processed_height(&self) -> CoreBlockHeight; /// Update chain state and process any matured transactions /// This should be called when the chain tip advances to a new height - fn update_synced_height(&mut self, current_height: u32); + fn update_last_processed_height(&mut self, current_height: u32); /// Mark UTXOs for a transaction as InstantSend-locked across all accounts /// and update the corresponding transaction record context. @@ -144,8 +147,8 @@ impl WalletInfoInterface for ManagedWalletInfo { self.metadata.birth_height = height; } - fn synced_height(&self) -> CoreBlockHeight { - self.metadata.synced_height + fn last_processed_height(&self) -> CoreBlockHeight { + self.metadata.last_processed_height } fn first_loaded_at(&self) -> u64 { @@ -175,6 +178,12 @@ impl WalletInfoInterface for ManagedWalletInfo { } utxos } + fn get_spendable_utxos(&self) -> BTreeSet<&Utxo> { + self.utxos() + .into_iter() + .filter(|utxo| utxo.is_spendable(self.last_processed_height())) + .collect() + } fn balance(&self) -> WalletCoreBalance { self.balance @@ -182,9 +191,9 @@ impl WalletInfoInterface for ManagedWalletInfo { fn update_balance(&mut self) { let mut balance = WalletCoreBalance::default(); - let synced_height = self.synced_height(); + let last_processed_height = self.last_processed_height(); for account in self.accounts.all_accounts_mut() { - account.update_balance(synced_height); + account.update_balance(last_processed_height); balance += *account.balance(); } self.balance = balance; @@ -212,7 +221,7 @@ impl WalletInfoInterface for ManagedWalletInfo { // Find txids of immature coinbase UTXOs for account in self.accounts.all_accounts() { for utxo in account.utxos.values() { - if utxo.is_coinbase && !utxo.is_mature(self.synced_height()) { + if utxo.is_coinbase && !utxo.is_mature(self.last_processed_height()) { immature_txids.insert(utxo.outpoint.txid); } } @@ -230,8 +239,8 @@ impl WalletInfoInterface for ManagedWalletInfo { transactions } - fn update_synced_height(&mut self, current_height: u32) { - self.metadata.synced_height = current_height; + fn update_last_processed_height(&mut self, current_height: u32) { + self.metadata.last_processed_height = current_height; // Update cached balance self.update_balance(); } diff --git a/key-wallet/src/wallet/metadata.rs b/key-wallet/src/wallet/metadata.rs index a2bd8025e..4f297b240 100644 --- a/key-wallet/src/wallet/metadata.rs +++ b/key-wallet/src/wallet/metadata.rs @@ -16,8 +16,8 @@ pub struct WalletMetadata { pub first_loaded_at: u64, /// Birth height (when wallet was created/restored) - 0 (genesis) if unknown pub birth_height: CoreBlockHeight, - /// Synced to block height - pub synced_height: CoreBlockHeight, + /// Last processed block height + pub last_processed_height: CoreBlockHeight, /// Last sync timestamp pub last_synced: Option, /// Total transactions From ceb349f891cd5a0dce6fa5d543816ee22a284fe2 Mon Sep 17 00:00:00 2001 From: xdustinface Date: Thu, 23 Apr 2026 09:22:17 +1000 Subject: [PATCH 2/2] refactor(wallet): rename filter_committed_height to synced_height Rename the committed filter-scan checkpoint from filter_committed_height to synced_height in the wallet interface, wallet manager, and filter sync manager. With synced_height already moved to last_processed_height in the previous commit, synced_height now clearly names the durable committed restart point. --- dash-spv/src/sync/filters/manager.rs | 8 +- key-wallet-ffi/FFI_API.md | 267 ++++++++++++--------- key-wallet-manager/src/lib.rs | 4 +- key-wallet-manager/src/process_block.rs | 8 +- key-wallet-manager/src/wallet_interface.rs | 6 +- key-wallet/src/managed_account/mod.rs | 5 +- 6 files changed, 161 insertions(+), 137 deletions(-) diff --git a/dash-spv/src/sync/filters/manager.rs b/dash-spv/src/sync/filters/manager.rs index b410df044..d800d0f95 100644 --- a/dash-spv/src/sync/filters/manager.rs +++ b/dash-spv/src/sync/filters/manager.rs @@ -83,7 +83,7 @@ impl>, filter_storage: Arc>, ) -> Self { - let committed_height = wallet.read().await.filter_committed_height(); + let committed_height = wallet.read().await.synced_height(); let stored_height = filter_storage.read().await.filter_tip_height().await.unwrap_or(0); let target_height = header_storage.read().await.get_tip().await.map(|t| t.height()).unwrap_or(0); @@ -158,11 +158,11 @@ impl SyncResult> { debug_assert!(self.is_idle(), "manager should have no in-flight state on start"); - // Use filter_committed_height for restart recovery instead of + // Use synced_height for restart recovery instead of // last_processed_height, which advances per-block and may exceed committed scan progress. let (wallet_birth_height, wallet_committed_height) = { let wallet = self.wallet.read().await; - (wallet.earliest_required_height().await, wallet.filter_committed_height()) + (wallet.earliest_required_height().await, wallet.synced_height()) }; // Get stored filters tip @@ -495,7 +495,7 @@ impl self.progress.committed_height() { self.progress.update_committed_height(end); - self.wallet.write().await.update_filter_committed_height(end); + self.wallet.write().await.update_synced_height(end); } self.processing_height = end + 1; diff --git a/key-wallet-ffi/FFI_API.md b/key-wallet-ffi/FFI_API.md index 41e2c5c85..934797af0 100644 --- a/key-wallet-ffi/FFI_API.md +++ b/key-wallet-ffi/FFI_API.md @@ -50,7 +50,7 @@ Functions: 19 | `wallet_manager_add_wallet_from_mnemonic` | Add a wallet from mnemonic to the manager (backward compatibility) # Safety... | wallet_manager | | `wallet_manager_add_wallet_from_mnemonic_return_serialized_bytes` | No description | wallet_manager | | `wallet_manager_add_wallet_from_mnemonic_with_options` | Add a wallet from mnemonic to the manager with options # Safety -... | wallet_manager | -| `wallet_manager_create` | Create a new wallet manager | wallet_manager | +| `wallet_manager_create` | Create a new wallet manager # Safety `error` must be a valid pointer to an... | wallet_manager | | `wallet_manager_current_height` | Get current height for a network # Safety - `manager` must be a valid... | wallet_manager | | `wallet_manager_describe` | Describe the wallet manager for a given network and return a newly allocated... | wallet_manager | | `wallet_manager_free` | Free wallet manager # Safety - `manager` must be a valid pointer to an... | wallet_manager | @@ -99,9 +99,9 @@ Functions: 64 | `managed_wallet_get_top_up_account_with_registration_index` | Get a managed IdentityTopUp account with a specific registration index This... | managed_account | | `managed_wallet_get_utxos` | Get all UTXOs from managed wallet info # Safety - `managed_info` must be a... | utxo | | `managed_wallet_info_free` | Free managed wallet info returned by wallet_manager_get_managed_wallet_info ... | managed_wallet | +| `managed_wallet_last_processed_height` | Get current last processed height from wallet info # Safety -... | managed_wallet | | `managed_wallet_mark_address_used` | Mark an address as used in the pool This updates the pool's tracking of... | address_pool | | `managed_wallet_set_gap_limit` | Set the gap limit for an address pool The gap limit determines how many... | address_pool | -| `managed_wallet_last_processed_height` | Get current last processed height from wallet info # Safety - `managed_wallet`... | managed_wallet | | `wallet_add_account` | Add an account to the wallet without xpub # Safety This function... | wallet | | `wallet_add_account_with_string_xpub` | Add an account to the wallet with xpub as string # Safety This function... | wallet | | `wallet_add_account_with_xpub_bytes` | Add an account to the wallet with xpub as byte array # Safety This... | wallet | @@ -190,7 +190,7 @@ Functions: 109 | `bls_account_get_extended_public_key_as_string` | No description | account | | `bls_account_get_is_watch_only` | No description | account | | `bls_account_get_network` | No description | account | -| `derivation_bip44_account_path` | Derive a BIP44 account path (m/44'/5'/account') | derivation | +| `derivation_bip44_account_path` | Derive a BIP44 account path (m/44'/5'/account') # Safety `path_out` must... | derivation | | `eddsa_account_derive_private_key_from_mnemonic` | No description | account_derivation | | `eddsa_account_derive_private_key_from_seed` | No description | account_derivation | | `eddsa_account_free` | No description | account | @@ -320,8 +320,8 @@ Functions: 6 | Function | Description | Module | |----------|-------------|--------| | `mnemonic_free` | Free a mnemonic string # Safety - `mnemonic` must be a valid pointer... | mnemonic | -| `mnemonic_generate` | Generate a new mnemonic with specified word count (12, 15, 18, 21, or 24) | mnemonic | -| `mnemonic_generate_with_language` | Generate a new mnemonic with specified language and word count | mnemonic | +| `mnemonic_generate` | Generate a new mnemonic with specified word count (12, 15, 18, 21, or 24) #... | mnemonic | +| `mnemonic_generate_with_language` | Generate a new mnemonic with specified language and word count # Safety ... | mnemonic | | `mnemonic_to_seed` | Convert mnemonic to seed with optional passphrase # Safety - `mnemonic`... | mnemonic | | `mnemonic_validate` | Validate a mnemonic phrase # Safety - `mnemonic` must be a valid... | mnemonic | | `mnemonic_word_count` | Get word count from mnemonic # Safety - `mnemonic` must be a valid... | mnemonic | @@ -332,11 +332,11 @@ Functions: 17 | Function | Description | Module | |----------|-------------|--------| -| `derivation_bip44_payment_path` | Derive a BIP44 payment path (m/44'/5'/account'/change/index) | derivation | -| `derivation_coinjoin_path` | Derive CoinJoin path (m/9'/5'/4'/account') | derivation | -| `derivation_identity_authentication_path` | Derive identity authentication path (m/9'/5'/5'/0'/identity_index'/key_index') | derivation | -| `derivation_identity_registration_path` | Derive identity registration path (m/9'/5'/5'/1'/index') | derivation | -| `derivation_identity_topup_path` | Derive identity top-up path (m/9'/5'/5'/2'/identity_index'/top_up_index') | derivation | +| `derivation_bip44_payment_path` | Derive a BIP44 payment path (m/44'/5'/account'/change/index) # Safety ... | derivation | +| `derivation_coinjoin_path` | Derive CoinJoin path (m/9'/5'/4'/account') # Safety `path_out` must point... | derivation | +| `derivation_identity_authentication_path` | Derive identity authentication path (m/9'/5'/5'/0'/identity_index'/key_index'... | derivation | +| `derivation_identity_registration_path` | Derive identity registration path (m/9'/5'/5'/1'/index') # Safety ... | derivation | +| `derivation_identity_topup_path` | Derive identity top-up path (m/9'/5'/5'/2'/identity_index'/top_up_index') #... | derivation | | `derivation_path_free` | Free derivation path arrays Note: This function expects the count to... | keys | | `derivation_path_parse` | Convert derivation path string to indices # Safety - `path` must be a... | keys | | `derivation_string_free` | Free derivation path string # Safety - `s` must be a valid pointer to a C... | derivation | @@ -455,10 +455,10 @@ wallet_manager_add_wallet_from_mnemonic(manager: *mut FFIWalletManager, mnemonic ``` **Description:** -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 +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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `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 - The caller must ensure all pointers remain valid for the duration of this call **Module:** `wallet_manager` @@ -481,10 +481,10 @@ wallet_manager_add_wallet_from_mnemonic_with_options(manager: *mut FFIWalletMana ``` **Description:** -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 +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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `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 - The caller must ensure all pointers remain valid for the duration of this call **Module:** `wallet_manager` @@ -497,7 +497,10 @@ wallet_manager_create(network: FFINetwork, error: *mut FFIError,) -> *mut FFIWal ``` **Description:** -Create a new wallet manager +Create a new wallet manager # Safety `error` must be a valid pointer to an `FFIError`. The returned pointer must be freed with `wallet_manager_free`. + +**Safety:** +`error` must be a valid pointer to an `FFIError`. The returned pointer must be freed with `wallet_manager_free`. **Module:** `wallet_manager` @@ -510,10 +513,10 @@ wallet_manager_current_height(manager: *const FFIWalletManager, error: *mut FFIE ``` **Description:** -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 +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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `manager` must be a valid pointer to an FFIWalletManager - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call **Module:** `wallet_manager` @@ -616,10 +619,10 @@ wallet_manager_get_managed_wallet_info(manager: *const FFIWalletManager, wallet_ ``` **Description:** -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() +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 - 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() **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() +- `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 - 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() **Module:** `wallet_manager` @@ -632,10 +635,10 @@ wallet_manager_get_wallet(manager: *const FFIWalletManager, wallet_id: *const u8 ``` **Description:** -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() +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 - The caller must ensure all pointers remain valid for the duration of this call - The returned wallet must be freed with wallet_free_const() **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() +- `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 - The caller must ensure all pointers remain valid for the duration of this call - The returned wallet must be freed with wallet_free_const() **Module:** `wallet_manager` @@ -648,10 +651,10 @@ wallet_manager_get_wallet_balance(manager: *const FFIWalletManager, wallet_id: * ``` **Description:** -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 +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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `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 - The caller must ensure all pointers remain valid for the duration of this call **Module:** `wallet_manager` @@ -664,10 +667,10 @@ wallet_manager_get_wallet_ids(manager: *const FFIWalletManager, wallet_ids_out: ``` **Description:** -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 +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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `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 - The caller must ensure all pointers remain valid for the duration of this call **Module:** `wallet_manager` @@ -690,10 +693,10 @@ wallet_manager_network(manager: *const FFIWalletManager, error: *mut FFIError,) ``` **Description:** -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 +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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `manager` must be a valid pointer to an FFIWalletManager - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call **Module:** `wallet_manager` @@ -706,10 +709,10 @@ wallet_manager_process_transaction(manager: *mut FFIWalletManager, tx_bytes: *co ``` **Description:** -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 FFITransactionContext - `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 +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 FFITransactionContext - `update_state_if_found` indicates whether to update wallet state when transaction is relevant - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call **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 FFITransactionContext - `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 +- `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 FFITransactionContext - `update_state_if_found` indicates whether to update wallet state when transaction is relevant - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call **Module:** `wallet_manager` @@ -722,10 +725,10 @@ wallet_manager_wallet_count(manager: *const FFIWalletManager, error: *mut FFIErr ``` **Description:** -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 +Get wallet count # Safety - `manager` must be a valid pointer to an FFIWalletManager instance - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call **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 +- `manager` must be a valid pointer to an FFIWalletManager instance - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call **Module:** `wallet_manager` @@ -888,10 +891,10 @@ managed_wallet_generate_addresses_to_index(managed_wallet: *mut FFIManagedWallet ``` **Description:** -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 +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 **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 +- `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 **Module:** `address_pool` @@ -920,10 +923,10 @@ managed_wallet_get_account_collection(manager: *const FFIWalletManager, wallet_i ``` **Description:** -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 +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 - The returned pointer must be freed with `managed_account_collection_free` when no longer needed **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 +- `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 - The returned pointer must be freed with `managed_account_collection_free` when no longer needed **Module:** `managed_account_collection` @@ -936,10 +939,10 @@ managed_wallet_get_account_count(manager: *const FFIWalletManager, wallet_id: *c ``` **Description:** -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 +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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `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 - The caller must ensure all pointers remain valid for the duration of this call **Module:** `managed_account` @@ -952,10 +955,10 @@ managed_wallet_get_address_pool_info(managed_wallet: *const FFIManagedWalletInfo ``` **Description:** -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 +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 **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 +- `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 **Module:** `address_pool` @@ -1112,10 +1115,10 @@ managed_wallet_get_utxos(managed_info: *const FFIManagedWalletInfo, utxos_out: * ``` **Description:** -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 +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 - 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 **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 +- `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 - 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 **Module:** `utxo` @@ -1137,51 +1140,51 @@ Free managed wallet info returned by wallet_manager_get_managed_wallet_info # S --- -#### `managed_wallet_mark_address_used` +#### `managed_wallet_last_processed_height` ```c -managed_wallet_mark_address_used(managed_wallet: *mut FFIManagedWalletInfo, address: *const c_char, error: *mut FFIError,) -> bool +managed_wallet_last_processed_height(managed_wallet: *const FFIManagedWalletInfo, error: *mut FFIError,) -> c_uint ``` **Description:** -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 +Get current last processed 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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call -**Module:** `address_pool` +**Module:** `managed_wallet` --- -#### `managed_wallet_set_gap_limit` +#### `managed_wallet_mark_address_used` ```c -managed_wallet_set_gap_limit(managed_wallet: *mut FFIManagedWalletInfo, account_type: FFIAccountType, account_index: c_uint, pool_type: FFIAddressPoolType, gap_limit: c_uint, error: *mut FFIError,) -> bool +managed_wallet_mark_address_used(managed_wallet: *mut FFIManagedWalletInfo, address: *const c_char, error: *mut FFIError,) -> bool ``` **Description:** -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 +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 **Safety:** -- `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - `error` must be a valid pointer to an FFIError or null +- `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 **Module:** `address_pool` --- -#### `managed_wallet_last_processed_height` +#### `managed_wallet_set_gap_limit` ```c -managed_wallet_last_processed_height(managed_wallet: *const FFIManagedWalletInfo, error: *mut FFIError,) -> c_uint +managed_wallet_set_gap_limit(managed_wallet: *mut FFIManagedWalletInfo, account_type: FFIAccountType, account_index: c_uint, pool_type: FFIAddressPoolType, gap_limit: c_uint, error: *mut FFIError,) -> bool ``` **Description:** -Get current last processed 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 +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 **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 +- `managed_wallet` must be a valid pointer to an FFIManagedWalletInfo - `error` must be a valid pointer to an FFIError -**Module:** `managed_wallet` +**Module:** `address_pool` --- @@ -1336,10 +1339,10 @@ wallet_create_from_mnemonic(mnemonic: *const c_char, passphrase: *const c_char, ``` **Description:** -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 +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 - 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 **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 +- `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 - 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 **Module:** `wallet` @@ -1352,10 +1355,10 @@ wallet_create_from_mnemonic_with_options(mnemonic: *const c_char, passphrase: *c ``` **Description:** -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 +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 - 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 **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 +- `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 - 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 **Module:** `wallet` @@ -1368,10 +1371,10 @@ wallet_create_from_seed(seed: *const u8, seed_len: usize, network: FFINetwork, e ``` **Description:** -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 +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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `seed` must be a valid pointer to a byte array of `seed_len` length - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call **Module:** `wallet` @@ -1384,10 +1387,10 @@ wallet_create_from_seed_with_options(seed: *const u8, seed_len: usize, network: ``` **Description:** -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 +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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `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 - The caller must ensure all pointers remain valid for the duration of this call **Module:** `wallet` @@ -1400,10 +1403,10 @@ wallet_create_managed_wallet(wallet: *const FFIWallet, error: *mut FFIError,) -> ``` **Description:** -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) +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 - The returned pointer must be freed with `managed_wallet_info_free` (or `ffi_managed_wallet_free` for compatibility) **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) +- `wallet` must be a valid pointer to an FFIWallet - `error` must be a valid pointer to an FFIError - The returned pointer must be freed with `managed_wallet_info_free` (or `ffi_managed_wallet_free` for compatibility) **Module:** `transaction_checking` @@ -1416,10 +1419,10 @@ wallet_create_random(network: FFINetwork, error: *mut FFIError,) -> *mut FFIWall ``` **Description:** -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 +Create a new random wallet (backward compatibility) # Safety - `error` must be a valid pointer to an FFIError structure - The caller must ensure the pointer remains valid for the duration of this call **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 +- `error` must be a valid pointer to an FFIError structure - The caller must ensure the pointer remains valid for the duration of this call **Module:** `wallet` @@ -1432,10 +1435,10 @@ wallet_create_random_with_options(network: FFINetwork, account_options: *const F ``` **Description:** -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 +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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `account_options` must be a valid pointer to FFIWalletAccountCreationOptions or null - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call **Module:** `wallet` @@ -1592,10 +1595,10 @@ wallet_get_account_collection(wallet: *const FFIWallet, error: *mut FFIError,) - ``` **Description:** -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 +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 - The returned pointer must be freed with `account_collection_free` when no longer needed **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 +- `wallet` must be a valid pointer to an FFIWallet instance - `error` must be a valid pointer to an FFIError structure - The returned pointer must be freed with `account_collection_free` when no longer needed **Module:** `account_collection` @@ -1656,10 +1659,10 @@ wallet_get_id(wallet: *const FFIWallet, id_out: *mut u8, error: *mut FFIError,) ``` **Description:** -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 +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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `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 - The caller must ensure all pointers remain valid for the duration of this call **Module:** `wallet` @@ -1704,10 +1707,10 @@ wallet_get_xpub(wallet: *const FFIWallet, account_index: c_uint, error: *mut FFI ``` **Description:** -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 +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 - 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 **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 +- `wallet` must be a valid pointer to an FFIWallet instance - `error` must be a valid pointer to an FFIError structure - 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 **Module:** `wallet` @@ -1720,10 +1723,10 @@ wallet_has_mnemonic(wallet: *const FFIWallet, error: *mut FFIError,) -> bool ``` **Description:** -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 +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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `wallet` must be a valid pointer to an FFIWallet instance - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call **Module:** `wallet` @@ -1736,10 +1739,10 @@ wallet_is_watch_only(wallet: *const FFIWallet, error: *mut FFIError,) -> bool ``` **Description:** -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 +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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `wallet` must be a valid pointer to an FFIWallet instance - `error` must be a valid pointer to an FFIError structure - The caller must ensure all pointers remain valid for the duration of this call **Module:** `wallet` @@ -2186,10 +2189,10 @@ account_derive_extended_private_key_at(account: *const FFIAccount, master_xpriv: ``` **Description:** -Derive an extended private key from an account at a given index, using the provided master xpriv. Returns an opaque FFIExtendedPrivKey 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`. +Derive an extended private key from an account at a given index, using the provided master xpriv. Returns an opaque FFIExtendedPrivKey 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. - The caller must free the returned pointer with `extended_private_key_free`. **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`. +- `account` and `master_xpriv` must be valid, non-null pointers allocated by this library. - `error` must be a valid pointer to an FFIError. - The caller must free the returned pointer with `extended_private_key_free`. **Module:** `account_derivation` @@ -2202,10 +2205,10 @@ account_derive_extended_private_key_from_mnemonic(account: *const FFIAccount, mn ``` **Description:** -Derive an extended private key from a mnemonic + optional passphrase at the given index. Returns an opaque FFIExtendedPrivKey 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 +Derive an extended private key from a mnemonic + optional passphrase at the given index. Returns an opaque FFIExtendedPrivKey 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 **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 +- `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 **Module:** `account_derivation` @@ -2218,10 +2221,10 @@ account_derive_extended_private_key_from_seed(account: *const FFIAccount, seed: ``` **Description:** -Derive an extended private key from a raw seed buffer at the given index. Returns an opaque FFIExtendedPrivKey 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 +Derive an extended private key from a raw seed buffer at the given index. Returns an opaque FFIExtendedPrivKey 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 **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 +- `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 **Module:** `account_derivation` @@ -2234,10 +2237,10 @@ account_derive_private_key_as_wif_at(account: *const FFIAccount, master_xpriv: * ``` **Description:** -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 +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 **Safety:** -- `account` and `master_xpriv` must be valid pointers allocated by this library - `error` must be a valid pointer to an FFIError or null +- `account` and `master_xpriv` must be valid pointers allocated by this library - `error` must be a valid pointer to an FFIError **Module:** `account_derivation` @@ -2250,10 +2253,10 @@ account_derive_private_key_at(account: *const FFIAccount, master_xpriv: *const F ``` **Description:** -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 +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 **Safety:** -- `account` and `master_xpriv` must be valid pointers allocated by this library - `error` must be a valid pointer to an FFIError or null +- `account` and `master_xpriv` must be valid pointers allocated by this library - `error` must be a valid pointer to an FFIError **Module:** `account_derivation` @@ -2266,10 +2269,10 @@ account_derive_private_key_from_mnemonic(account: *const FFIAccount, mnemonic: * ``` **Description:** -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 +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 **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 +- `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 **Module:** `account_derivation` @@ -2282,10 +2285,10 @@ account_derive_private_key_from_seed(account: *const FFIAccount, seed: *const u8 ``` **Description:** -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 +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 **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 +- `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 **Module:** `account_derivation` @@ -2448,7 +2451,10 @@ derivation_bip44_account_path(network: FFINetwork, account_index: c_uint, path_o ``` **Description:** -Derive a BIP44 account path (m/44'/5'/account') +Derive a BIP44 account path (m/44'/5'/account') # Safety `path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. + +**Safety:** +`path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. **Module:** `derivation` @@ -3509,10 +3515,10 @@ address_pool_get_address_at_index(pool: *const FFIAddressPool, index: u32, error ``` **Description:** -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` +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 - The returned FFIAddressInfo must be freed using `address_info_free` **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` +- `pool` must be a valid pointer to an FFIAddressPool - `error` must be a valid pointer to an FFIError - The returned FFIAddressInfo must be freed using `address_info_free` **Module:** `address_pool` @@ -3525,10 +3531,10 @@ address_pool_get_addresses_in_range(pool: *const FFIAddressPool, start_index: u3 ``` **Description:** -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` +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 - The returned array must be freed using `address_info_array_free` **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` +- `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 - The returned array must be freed using `address_info_array_free` **Module:** `address_pool` @@ -3639,10 +3645,10 @@ transaction_classify(tx_bytes: *const u8, tx_len: usize, error: *mut FFIError,) ``` **Description:** -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 +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 - The returned string must be freed by the caller **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 +- `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 - The returned string must be freed by the caller **Module:** `transaction_checking` @@ -3794,14 +3800,14 @@ Free UTXO array # Safety - `utxos` must be a valid pointer to an array of FFIU #### `bip38_decrypt_private_key` ```c -bip38_decrypt_private_key(encrypted_key: *const c_char, passphrase: *const c_char, error: *mut FFIError,) -> *mut c_char +bip38_decrypt_private_key(_encrypted_key: *const c_char, _passphrase: *const c_char, error: *mut FFIError,) -> *mut c_char ``` **Description:** -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 +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 **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 +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 **Module:** `bip38` @@ -3810,14 +3816,14 @@ This function is unsafe because it dereferences raw pointers: - `encrypted_key` #### `bip38_encrypt_private_key` ```c -bip38_encrypt_private_key(private_key: *const c_char, passphrase: *const c_char, error: *mut FFIError,) -> *mut c_char +bip38_encrypt_private_key(_private_key: *const c_char, _passphrase: *const c_char, error: *mut FFIError,) -> *mut c_char ``` **Description:** -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 +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 **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 +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 **Module:** `bip38` @@ -3830,10 +3836,10 @@ derivation_derive_private_key_from_seed(seed: *const u8, seed_len: usize, path: ``` **Description:** -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 +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 - The caller must ensure all pointers remain valid for the duration of this call **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 +- `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 - The caller must ensure all pointers remain valid for the duration of this call **Module:** `derivation` @@ -3846,10 +3852,10 @@ derivation_new_master_key(seed: *const u8, seed_len: usize, network: FFINetwork, ``` **Description:** -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 +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 - The caller must ensure the seed pointer remains valid for the duration of this call **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 +- `seed` must be a valid pointer to a byte array of `seed_len` length - `error` must be a valid pointer to an FFIError structure - The caller must ensure the seed pointer remains valid for the duration of this call **Module:** `derivation` @@ -3890,7 +3896,7 @@ Get the private key from an extended private key Extracts the non-extended priv #### `extended_private_key_to_string` ```c -extended_private_key_to_string(key: *const FFIExtendedPrivKey, network: FFINetwork, error: *mut FFIError,) -> *mut c_char +extended_private_key_to_string(key: *const FFIExtendedPrivKey, _network: FFINetwork, error: *mut FFIError,) -> *mut c_char ``` **Description:** @@ -3938,7 +3944,7 @@ Get the public key from an extended public key Extracts the non-extended public #### `extended_public_key_to_string` ```c -extended_public_key_to_string(key: *const FFIExtendedPubKey, network: FFINetwork, error: *mut FFIError,) -> *mut c_char +extended_public_key_to_string(key: *const FFIExtendedPubKey, _network: FFINetwork, error: *mut FFIError,) -> *mut c_char ``` **Description:** @@ -4036,11 +4042,14 @@ Free a mnemonic string # Safety - `mnemonic` must be a valid pointer created b #### `mnemonic_generate` ```c -mnemonic_generate(word_count: c_uint, error: *mut FFIError) -> *mut c_char +mnemonic_generate(word_count: c_uint, error: *mut FFIError,) -> *mut c_char ``` **Description:** -Generate a new mnemonic with specified word count (12, 15, 18, 21, or 24) +Generate a new mnemonic with specified word count (12, 15, 18, 21, or 24) # Safety `error` must be a valid pointer to an `FFIError`. The returned string must be freed with `mnemonic_free`. + +**Safety:** +`error` must be a valid pointer to an `FFIError`. The returned string must be freed with `mnemonic_free`. **Module:** `mnemonic` @@ -4053,7 +4062,10 @@ mnemonic_generate_with_language(word_count: c_uint, language: FFILanguage, error ``` **Description:** -Generate a new mnemonic with specified language and word count +Generate a new mnemonic with specified language and word count # Safety `error` must be a valid pointer to an `FFIError`. The returned string must be freed with `mnemonic_free`. + +**Safety:** +`error` must be a valid pointer to an `FFIError`. The returned string must be freed with `mnemonic_free`. **Module:** `mnemonic` @@ -4116,7 +4128,10 @@ derivation_bip44_payment_path(network: FFINetwork, account_index: c_uint, is_cha ``` **Description:** -Derive a BIP44 payment path (m/44'/5'/account'/change/index) +Derive a BIP44 payment path (m/44'/5'/account'/change/index) # Safety `path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. + +**Safety:** +`path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. **Module:** `derivation` @@ -4129,7 +4144,10 @@ derivation_coinjoin_path(network: FFINetwork, account_index: c_uint, path_out: * ``` **Description:** -Derive CoinJoin path (m/9'/5'/4'/account') +Derive CoinJoin path (m/9'/5'/4'/account') # Safety `path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. + +**Safety:** +`path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. **Module:** `derivation` @@ -4142,7 +4160,10 @@ derivation_identity_authentication_path(network: FFINetwork, identity_index: c_u ``` **Description:** -Derive identity authentication path (m/9'/5'/5'/0'/identity_index'/key_index') +Derive identity authentication path (m/9'/5'/5'/0'/identity_index'/key_index') # Safety `path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. + +**Safety:** +`path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. **Module:** `derivation` @@ -4155,7 +4176,10 @@ derivation_identity_registration_path(network: FFINetwork, identity_index: c_uin ``` **Description:** -Derive identity registration path (m/9'/5'/5'/1'/index') +Derive identity registration path (m/9'/5'/5'/1'/index') # Safety `path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. + +**Safety:** +`path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. **Module:** `derivation` @@ -4168,7 +4192,10 @@ derivation_identity_topup_path(network: FFINetwork, identity_index: c_uint, topu ``` **Description:** -Derive identity top-up path (m/9'/5'/5'/2'/identity_index'/top_up_index') +Derive identity top-up path (m/9'/5'/5'/2'/identity_index'/top_up_index') # Safety `path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. + +**Safety:** +`path_out` must point to a writable buffer of at least `path_max_len` bytes and `error` must be a valid pointer to an `FFIError`. **Module:** `derivation` diff --git a/key-wallet-manager/src/lib.rs b/key-wallet-manager/src/lib.rs index b5c7b9e88..f1a0ff118 100644 --- a/key-wallet-manager/src/lib.rs +++ b/key-wallet-manager/src/lib.rs @@ -93,7 +93,7 @@ pub struct WalletManager { /// Last fully processed block height. last_processed_height: CoreBlockHeight, /// Height at which filter scanning was last committed. - filter_committed_height: CoreBlockHeight, + synced_height: CoreBlockHeight, /// Immutable wallets indexed by wallet ID wallets: BTreeMap, /// Mutable wallet info indexed by wallet ID @@ -112,7 +112,7 @@ impl WalletManager { Self { network, last_processed_height: 0, - filter_committed_height: 0, + synced_height: 0, wallets: BTreeMap::new(), wallet_infos: BTreeMap::new(), structural_revision: 0, diff --git a/key-wallet-manager/src/process_block.rs b/key-wallet-manager/src/process_block.rs index e7b3cf770..112a57bc3 100644 --- a/key-wallet-manager/src/process_block.rs +++ b/key-wallet-manager/src/process_block.rs @@ -113,12 +113,12 @@ impl WalletInterface for WalletM self.emit_balance_changes(&snapshot); } - fn filter_committed_height(&self) -> CoreBlockHeight { - self.filter_committed_height + fn synced_height(&self) -> CoreBlockHeight { + self.synced_height } - fn update_filter_committed_height(&mut self, height: CoreBlockHeight) { - self.filter_committed_height = height; + fn update_synced_height(&mut self, height: CoreBlockHeight) { + self.synced_height = height; if height > self.last_processed_height { self.update_last_processed_height(height); } diff --git a/key-wallet-manager/src/wallet_interface.rs b/key-wallet-manager/src/wallet_interface.rs index 44c815ac0..90e01e80d 100644 --- a/key-wallet-manager/src/wallet_interface.rs +++ b/key-wallet-manager/src/wallet_interface.rs @@ -94,13 +94,13 @@ pub trait WalletInterface: Send + Sync + 'static { /// Return the height at which filter scanning was last committed. /// Defaults to `last_processed_height()` for implementations that don't separate these concepts. // TODO: This can probably somehow be combined with last_processed_height(). - fn filter_committed_height(&self) -> CoreBlockHeight { + fn synced_height(&self) -> CoreBlockHeight { self.last_processed_height() } - /// Update the filter committed height. Call when a height is fully processed + /// Update the committed synced height. Call when a height is fully processed /// (including any rescans for newly discovered addresses). - fn update_filter_committed_height(&mut self, height: CoreBlockHeight) { + fn update_synced_height(&mut self, height: CoreBlockHeight) { if height > self.last_processed_height() { self.update_last_processed_height(height); } diff --git a/key-wallet/src/managed_account/mod.rs b/key-wallet/src/managed_account/mod.rs index 6ce168c3f..2633cb0b0 100644 --- a/key-wallet/src/managed_account/mod.rs +++ b/key-wallet/src/managed_account/mod.rs @@ -560,10 +560,7 @@ impl ManagedCoreAccount { /// aggregating across the wallet, since spendability is /// account-type specific. pub fn spendable_utxos(&self, last_processed_height: u32) -> BTreeSet<&Utxo> { - self.utxos - .values() - .filter(|utxo| utxo.is_spendable(last_processed_height)) - .collect() + self.utxos.values().filter(|utxo| utxo.is_spendable(last_processed_height)).collect() } /// Update the account balance.