feat(key-wallet): add keep-finalized-transactions Cargo feature (#733)

* feat(key-wallet): add `keep-finalized-transactions` feature

By default, records of chainlocked transactions are now dropped from
each managed account's in-memory `transactions` map; only their txids
are retained (in a new `finalized_txids` set on `ManagedCoreKeysAccount`)
to keep dedup, `has_transaction`, and finality queries working. The
opt-in `keep-finalized-transactions` Cargo feature reverts to the
old behavior — every processed transaction stays in the map for the
wallet's lifetime.

The drop is driven off `TransactionContext::is_finalized_in_block`
(chainlock only), not `is_finalized` (chainlock or IS-lock), so
IS-locked records survive long enough to absorb the surrounding
block-confirmation event (xdustinface review on #709).

`confirm_transaction` now returns `Option<TransactionRecord>` so
callers always observe the record even when it's about to be dropped.

The feature is forwarded through `key-wallet-manager` and
`key-wallet-ffi`. Three FFI accessors that walk the full
`transactions` map (`managed_core_account_get_transaction_count`,
`managed_core_account_get_transactions`,
`managed_core_account_free_transactions`) are gated to the feature
because they would otherwise return a partial history.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(dash-spv-ffi): enable `keep-finalized-transactions` for tests

Integration tests under `dash-spv-ffi/tests/dashd_sync/` walk the full
per-account transaction history (`managed_core_account_get_transactions`,
`managed_core_account_get_transaction_count`,
`managed_core_account_free_transactions`) to verify end-to-end wallet
sync against a regtest dashd. These accessors are gated behind the
`keep-finalized-transactions` feature on `key-wallet-ffi`, so under the
default feature set they aren't compiled in and the test build fails to
resolve the imports.

Add `key-wallet-ffi` as a dev-dependency with the feature enabled.
Cargo unifies features across the build graph at test time, which
makes the gated accessors available in the test binaries without
expanding the lib crate's default feature surface.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor(key-wallet): align finalization with chainlock-only semantics

Address xdustinface review feedback on PR #733:

- Drop `TransactionContext::is_finalized()` (the soft IS-or-chainlock
  check). The wallet now treats only a chainlock as finality.
- Rename `TransactionContext::is_finalized_in_block()` to
  `is_chain_locked()` so the predicate name describes the variant
  rather than overloading "finalized" — same naming style as the
  existing `is_instant_send()` helper.
- Drop `ManagedAccountTrait::transaction_is_finalized()` (the
  unused soft-finality variant) and rename
  `transaction_is_finalized_in_block()` to `transaction_is_finalized()`.
  Now that there's a single finalization concept, the trait method
  name aligns with the feature name.
- Replace runtime `if cfg!(...) { ... } else { ... }` branches in
  `ManagedCoreKeysAccount::has_transaction` and
  `transaction_is_finalized` with two `#[cfg]`-gated function bodies
  — one per feature configuration. Same for the chainlock-driven
  drop call in `confirm_transaction` / `record_transaction`: the
  `let drop_now = …` binding now only exists when the feature is off,
  removing the `#[allow(unused_variables)]` workaround.
- Rewrite the doc on `has_transaction` so it's clear what it actually
  reports (live record OR finalized-txid marker) and how callers use
  it (distinguish brand-new sightings from re-processings) instead of
  the misleading "dedup signal in `confirm_transaction`" wording.

Drop logic still triggers on the strict `is_chain_locked()` check —
IS-locked-but-not-yet-chainlocked records still survive so the
surrounding block-confirmation event can populate height / block
hash before the chainlock catches up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(key-wallet): fix stale `transaction_is_finalized_in_block` mention

The previous commit renamed the trait method to `transaction_is_finalized`
but missed this Cargo.toml feature-doc reference. Caught by CodeRabbit on
PR #733.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: QuantumExplorer

dash-spv-ffi/Cargo.toml

@@ -28,6 +28,12 @@ clap = { version = "4.5", features = ["derive"] }
 
 [dev-dependencies]
 dash-spv = { path = "../dash-spv", features = ["test-utils"] }
+# Tests inspect per-account transaction history end-to-end (including
+# chainlocked transactions), which requires the `keep-finalized-transactions`
+# feature on `key-wallet-ffi`. Cargo unifies features across the build graph at
+# test time, so this enables the gated FFI accessors in test builds without
+# changing the lib's default feature surface.
+key-wallet-ffi = { path = "../key-wallet-ffi", features = ["keep-finalized-transactions"] }
 serial_test = "3.0"
 tempfile = "3.8"
 

key-wallet-ffi/Cargo.toml

@@ -18,6 +18,16 @@ bip38 = ["key-wallet/bip38"]
 bincode = ["key-wallet/bincode", "key-wallet-manager/bincode"]
 eddsa = ["dashcore/eddsa", "key-wallet/eddsa"]
 bls = ["dashcore/bls", "key-wallet/bls"]
+# Forward to `key-wallet/keep-finalized-transactions` (via key-wallet-manager).
+# With this on, every processed transaction (including chainlocked ones)
+# stays in the in-memory `transactions` map for the wallet's lifetime.
+# With it off (the default), records of chainlocked transactions are
+# dropped and only their txids are kept (in `finalized_txids`) for dedup.
+# See `key-wallet`'s feature documentation for details.
+keep-finalized-transactions = [
+    "key-wallet/keep-finalized-transactions",
+    "key-wallet-manager/keep-finalized-transactions",
+]
 
 [dependencies]
 key-wallet = { path = "../key-wallet" }

key-wallet-ffi/FFI_API.md

@@ -230,15 +230,15 @@ Functions: 108
 | `managed_account_collection_summary_data` | Get structured account collection summary data for managed collection ... | managed_account_collection |
 | `managed_account_collection_summary_free` | Free a managed account collection summary and all its allocated memory  #... | managed_account_collection |
 | `managed_core_account_free` | Free a managed account handle  # Safety  - `account` must be a valid pointer... | managed_account |
-| `managed_core_account_free_transactions` | Free transactions array returned by managed_core_account_get_transactions  #... | managed_account |
+| `managed_core_account_free_transactions` | Free transactions array returned by managed_core_account_get_transactions ... | managed_account |
 | `managed_core_account_get_account_type` | Get the account type of a managed account  # Safety  - `account` must be a... | managed_account |
 | `managed_core_account_get_address_pool` | Get an address pool from a managed account by type  This function returns... | managed_account |
 | `managed_core_account_get_balance` | Get the balance of a managed account  # Safety  - `account` must be a valid... | managed_account |
 | `managed_core_account_get_external_address_pool` | Get the external address pool from a managed account  This function returns... | managed_account |
 | `managed_core_account_get_index` | Get the account index from a managed account  Returns the primary account... | managed_account |
 | `managed_core_account_get_internal_address_pool` | Get the internal address pool from a managed account  This function returns... | managed_account |
 | `managed_core_account_get_network` | Get the network of a managed account  # Safety  - `account` must be a valid... | managed_account |
-| `managed_core_account_get_transaction_count` | Get the number of transactions in a managed account  # Safety  - `account`... | managed_account |
+| `managed_core_account_get_transaction_count` | Get the number of transactions in a managed account  Only available with the... | managed_account |
 | `managed_core_account_get_transactions` | Get all transactions from a managed account  Returns an array of... | managed_account |
 | `managed_core_account_get_utxo_count` | Get the number of UTXOs in a managed account  # Safety  - `account` must be... | managed_account |
 | `managed_platform_account_free` | Free a managed platform account handle  # Safety  - `account` must be a... | managed_account |
@@ -3047,7 +3047,7 @@ managed_core_account_free_transactions(transactions: *mut FFITransactionRecord,
 ```
 
 **Description:**
-Free transactions array returned by managed_core_account_get_transactions  # Safety  - `transactions` must be a pointer returned by `managed_core_account_get_transactions` - `count` must be the count returned by `managed_core_account_get_transactions` - This function must only be called once per allocation
+Free transactions array returned by managed_core_account_get_transactions  Only available with the `keep-finalized-transactions` Cargo feature, in which configuration `managed_core_account_get_transactions` is also available — the two functions are paired.  # Safety  - `transactions` must be a pointer returned by `managed_core_account_get_transactions` - `count` must be the count returned by `managed_core_account_get_transactions` - This function must only be called once per allocation
 
 **Safety:**
 - `transactions` must be a pointer returned by `managed_core_account_get_transactions` - `count` must be the count returned by `managed_core_account_get_transactions` - This function must only be called once per allocation
@@ -3175,7 +3175,7 @@ managed_core_account_get_transaction_count(account: *const FFIManagedCoreAccount
 ```
 
 **Description:**
-Get the number of transactions in a managed account  # Safety  - `account` must be a valid pointer to an FFIManagedCoreAccount instance
+Get the number of transactions in a managed account  Only available with the `keep-finalized-transactions` Cargo feature. With the feature off (the default), records of chainlocked transactions are dropped from the in-memory map, so the count would not reflect the full history — the function is intentionally not exposed.  # Safety  - `account` must be a valid pointer to an FFIManagedCoreAccount instance
 
 **Safety:**
 - `account` must be a valid pointer to an FFIManagedCoreAccount instance
@@ -3191,7 +3191,7 @@ managed_core_account_get_transactions(account: *const FFIManagedCoreAccount, tra
 ```
 
 **Description:**
-Get all transactions from a managed account  Returns an array of FFITransactionRecord structures.  # Safety  - `account` must be a valid pointer to an FFIManagedCoreAccount instance - `transactions_out` must be a valid pointer to receive the transactions array pointer - `count_out` must be a valid pointer to receive the count - The caller must free the returned array using `managed_core_account_free_transactions`
+Get all transactions from a managed account  Returns an array of FFITransactionRecord structures.  Only available with the `keep-finalized-transactions` Cargo feature. With the feature off (the default), records of chainlocked transactions are dropped from the in-memory map, so this would only return a partial history — the function is intentionally not exposed.  # Safety  - `account` must be a valid pointer to an FFIManagedCoreAccount instance - `transactions_out` must be a valid pointer to receive the transactions array pointer - `count_out` must be a valid pointer to receive the count - The caller must free the returned array using `managed_core_account_free_transactions`
 
 **Safety:**
 - `account` must be a valid pointer to an FFIManagedCoreAccount instance - `transactions_out` must be a valid pointer to receive the transactions array pointer - `count_out` must be a valid pointer to receive the count - The caller must free the returned array using `managed_core_account_free_transactions`

key-wallet-ffi/src/managed_account.rs

@@ -7,6 +7,7 @@
 use dash_network::ffi::FFINetwork;
 use dashcore::hashes::Hash;
 use std::os::raw::{c_char, c_uint};
+#[cfg(feature = "keep-finalized-transactions")]
 use std::ptr::slice_from_raw_parts_mut;
 use std::sync::Arc;
 
@@ -614,8 +615,14 @@ pub unsafe extern "C" fn managed_core_account_get_balance(
     true
 }
 
+#[cfg(feature = "keep-finalized-transactions")]
 /// Get the number of transactions in a managed account
 ///
+/// Only available with the `keep-finalized-transactions` Cargo feature. With
+/// the feature off (the default), records of chainlocked transactions are
+/// dropped from the in-memory map, so the count would not reflect the full
+/// history — the function is intentionally not exposed.
+///
 /// # Safety
 ///
 /// - `account` must be a valid pointer to an FFIManagedCoreAccount instance
@@ -914,10 +921,16 @@ impl Drop for FFITransactionRecord {
     }
 }
 
+#[cfg(feature = "keep-finalized-transactions")]
 /// Get all transactions from a managed account
 ///
 /// Returns an array of FFITransactionRecord structures.
 ///
+/// Only available with the `keep-finalized-transactions` Cargo feature. With
+/// the feature off (the default), records of chainlocked transactions are
+/// dropped from the in-memory map, so this would only return a partial
+/// history — the function is intentionally not exposed.
+///
 /// # Safety
 ///
 /// - `account` must be a valid pointer to an FFIManagedCoreAccount instance
@@ -951,8 +964,13 @@ pub unsafe extern "C" fn managed_core_account_get_transactions(
     true
 }
 
+#[cfg(feature = "keep-finalized-transactions")]
 /// Free transactions array returned by managed_core_account_get_transactions
 ///
+/// Only available with the `keep-finalized-transactions` Cargo feature, in
+/// which configuration `managed_core_account_get_transactions` is also
+/// available — the two functions are paired.
+///
 /// # Safety
 ///
 /// - `transactions` must be a pointer returned by `managed_core_account_get_transactions`
@@ -1547,10 +1565,13 @@ pub unsafe extern "C" fn managed_platform_account_result_free_error(
 mod tests {
     use super::*;
     use crate::address_pool::address_pool_free;
+    use crate::types::{FFIAccountCreationOptionType, FFIWalletAccountCreationOptions};
+    // These types are only used by the FFITransactionRecord tests, which run
+    // only when transactions stay in memory.
+    #[cfg(feature = "keep-finalized-transactions")]
     use crate::types::{
-        FFIAccountCreationOptionType, FFIBlockInfo, FFIInputDetail, FFIOutputDetail, FFIOutputRole,
-        FFITransactionContext, FFITransactionContextType, FFITransactionDirection,
-        FFITransactionType, FFIWalletAccountCreationOptions,
+        FFIBlockInfo, FFIInputDetail, FFIOutputDetail, FFIOutputRole, FFITransactionContext,
+        FFITransactionContextType, FFITransactionDirection, FFITransactionType,
     };
     use crate::wallet_manager::{
         wallet_manager_add_wallet_from_mnemonic_with_options, wallet_manager_create,
@@ -1828,9 +1849,15 @@ mod tests {
             assert_eq!(balance_out.locked, 0);
             assert_eq!(balance_out.total, 0);
 
-            // Test get_transaction_count
-            let tx_count = managed_core_account_get_transaction_count(account);
-            assert_eq!(tx_count, 0); // Initially no transactions
+            // Test get_transaction_count (only available with the
+            // `keep-finalized-transactions` feature; without it the function
+            // is not exposed because chainlocked records are pruned and the
+            // count would be incomplete)
+            #[cfg(feature = "keep-finalized-transactions")]
+            {
+                let tx_count = managed_core_account_get_transaction_count(account);
+                assert_eq!(tx_count, 0); // Initially no transactions
+            }
 
             // Test get_utxo_count
             let utxo_count = managed_core_account_get_utxo_count(account);
@@ -1858,8 +1885,11 @@ mod tests {
             let account_type = managed_core_account_get_account_type(ptr::null(), &mut index_out);
             assert_eq!(account_type, FFIAccountKind::StandardBIP44); // Default type
 
-            let tx_count = managed_core_account_get_transaction_count(ptr::null());
-            assert_eq!(tx_count, 0);
+            #[cfg(feature = "keep-finalized-transactions")]
+            {
+                let tx_count = managed_core_account_get_transaction_count(ptr::null());
+                assert_eq!(tx_count, 0);
+            }
 
             let utxo_count = managed_core_account_get_utxo_count(ptr::null());
             assert_eq!(utxo_count, 0);
@@ -2080,6 +2110,7 @@ mod tests {
         }
     }
 
+    #[cfg(feature = "keep-finalized-transactions")]
     #[test]
     fn test_free_transactions_null_safety() {
         unsafe {
@@ -2088,6 +2119,7 @@ mod tests {
         }
     }
 
+    #[cfg(feature = "keep-finalized-transactions")]
     #[test]
     fn test_ffi_transaction_record_roundtrip() {
         let mut records = Vec::new();

key-wallet-manager/Cargo.toml

@@ -14,6 +14,13 @@ bincode = ["key-wallet/bincode", "dep:bincode"]
 test-utils = ["key-wallet/test-utils"]
 bls = ["key-wallet/bls"]
 eddsa = ["key-wallet/eddsa"]
+# Forward to `key-wallet/keep-finalized-transactions`. With this on,
+# every processed transaction (including chainlocked ones) stays in
+# the in-memory `transactions` map for the wallet's lifetime. With
+# it off (the default), records of chainlocked transactions are
+# dropped and only their txids are kept (in `finalized_txids`) for
+# dedup. See `key-wallet`'s feature documentation for details.
+keep-finalized-transactions = ["key-wallet/keep-finalized-transactions"]
 
 [dependencies]
 key-wallet = { path = "../key-wallet", default-features = false }

key-wallet/Cargo.toml

@@ -16,6 +16,19 @@ bip38 = ["scrypt", "aes", "bs58", "rand"]
 eddsa = ["dashcore/eddsa"]
 bls = ["dashcore/bls"]
 test-utils = ["dashcore/test-utils"]
+# Keep the full `TransactionRecord` for transactions that have reached a
+# "finalized in block" state — i.e. they have a ChainLock confirming the
+# block they were mined in. With this feature ON, every processed
+# transaction (including ones already chainlocked) stays in the
+# `transactions` map for the wallet's lifetime; finalization is implicit
+# in the stored `TransactionContext`. With it OFF (the default), records
+# of chainlocked transactions are dropped from the map and a per-account
+# `finalized_txids: HashSet<Txid>` retains only their txids so
+# `has_transaction` / `transaction_is_finalized` still answer
+# correctly. An InstantSend lock alone does NOT trigger record dropping
+# — we keep the record around so the surrounding block confirmation can
+# still write its height / block hash before the chainlock arrives.
+keep-finalized-transactions = []
 
 [dependencies]
 internals = { path = "../internals", package = "dashcore-private" }

key-wallet/src/managed_account/managed_account_trait.rs

@@ -44,6 +44,26 @@ pub trait ManagedAccountTrait {
     /// Get mutable transactions
     fn transactions_mut(&mut self) -> &mut BTreeMap<Txid, TransactionRecord>;
 
+    /// Returns `true` if this account has already processed `txid`,
+    /// whether it is still represented as a full record in `transactions`
+    /// or has been pruned (under the default feature configuration) and
+    /// is now only retained as a finalized-txid marker. Used by callers
+    /// that need to distinguish a brand-new sighting from a re-processing
+    /// (mempool → block, IS-lock arrival, chainlock, …).
+    fn has_transaction(&self, txid: &Txid) -> bool;
+
+    /// Returns `true` if `txid` has been mined in a block that is itself
+    /// chainlocked — the only finality signal we treat as terminal
+    /// (mirrors [`crate::transaction_checking::TransactionContext::is_chain_locked`]).
+    ///
+    /// `InBlock` alone is not enough (the block can still be reorganized
+    /// out), and `InstantSend` alone is not enough either (the
+    /// surrounding block confirmation may still arrive and write the
+    /// height / block hash before the chainlock catches up). Only
+    /// `InChainLockedBlock` qualifies. This is the trigger for dropping
+    /// the full record under the default feature configuration.
+    fn transaction_is_finalized(&self, txid: &Txid) -> bool;
+
     /// Return the current monitor revision.
     ///
     /// Bumped whenever the monitored address set changes (e.g. new addresses