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>

Author: QuantumExplorer

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_in_block` 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,35 @@ 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's still mutable in `transactions` or has been
+    /// finalized-and-pruned (under the default feature configuration).
+    /// Used as the dedup signal in `confirm_transaction`.
+    fn has_transaction(&self, txid: &Txid) -> bool;
+
+    /// Returns `true` if `txid` has reached a finalized state — i.e. it
+    /// has either an InstantSend lock or a ChainLock and is no longer
+    /// expected to change.
+    ///
+    /// This is the *soft* finality check (mirrors
+    /// [`crate::transaction_checking::TransactionContext::is_finalized`]).
+    /// Use [`Self::transaction_is_finalized_in_block`] for the stricter
+    /// "fully confirmed in a chainlocked block" answer that drives
+    /// memory-pruning decisions.
+    fn transaction_is_finalized(&self, txid: &Txid) -> bool;
+
+    /// Returns `true` if `txid` has been mined in a block that is itself
+    /// chainlocked — the strongest finality signal (mirrors
+    /// [`crate::transaction_checking::TransactionContext::is_finalized_in_block`]).
+    ///
+    /// `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_in_block(&self, txid: &Txid) -> bool;
+
     /// Return the current monitor revision.
     ///
     /// Bumped whenever the monitored address set changes (e.g. new addresses