From 183d07fa818e5b6d69a63f87ae5c10d459c48f02 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Mon, 28 Sep 2026 11:46:56 +0700 Subject: [PATCH 1/3] feat(key-wallet)!: lock masternode collateral out of coin selection A wallet now locks the outputs it owns that back a registered masternode, so ordinary sends never spend them; an explicit unlock is available. Spending the collateral would end the registration. The wallet keeps one set of locked outpoints, `ManagedWalletInfo::locked_outpoints`, like Dash Core's `setLockedCoins`. Every ProRegTx the wallet processes adds its collateral: the outpoint it names, or its own output at `collateralIndex` when the collateral txid is null. The collateral may arrive before or after the ProRegTx. `lock_outpoint` and `unlock_outpoint` lock and unlock by hand, and only an unlock removes an entry. A ProUpRevTx or a replacing ProRegTx leaves the collateral locked; spending it removes the coin and leaves an entry with nothing to act on. Coin selection sees only `Utxo`s, so the wallet keeps each held coin's `is_locked` equal to membership in the set: when the coin arrives, on lock and unlock, and on every balance refresh. `is_spendable`, every selection strategy including the `All` drain, the spendable balance and the asset-lock builder follow from that, and `fund_from` also drops a seeded copy of a coin the account holds locked. The set is serialized with the wallet (`serde(default)`), and each check lists the outpoints it locked in `TransactionCheckResult::locked_outpoints` for stores that persist wallet state their own way. Co-Authored-By: Claude Opus 5.5 --- .../managed_core_funds_account.rs | 6 +- key-wallet/src/tests/balance_tests.rs | 9 +- .../src/tests/locked_outpoints_tests.rs | 582 ++++++++++++++++++ key-wallet/src/tests/mod.rs | 2 + .../transaction_checking/account_checker.rs | 11 + .../transaction_checking/wallet_checker.rs | 55 +- key-wallet/src/utxo.rs | 20 +- key-wallet/src/wallet/balance.rs | 3 +- .../managed_wallet_info/locked_outpoints.rs | 255 ++++++++ .../src/wallet/managed_wallet_info/mod.rs | 16 +- .../transaction_builder.rs | 21 +- .../wallet_info_interface.rs | 7 +- 12 files changed, 972 insertions(+), 15 deletions(-) create mode 100644 key-wallet/src/tests/locked_outpoints_tests.rs create mode 100644 key-wallet/src/wallet/managed_wallet_info/locked_outpoints.rs diff --git a/key-wallet/src/managed_account/managed_core_funds_account.rs b/key-wallet/src/managed_account/managed_core_funds_account.rs index e075f977c..b40e95962 100644 --- a/key-wallet/src/managed_account/managed_core_funds_account.rs +++ b/key-wallet/src/managed_account/managed_core_funds_account.rs @@ -379,9 +379,9 @@ impl ManagedCoreFundsAccount { // scratch, so carry forward flags that must not regress. An // InstantSend lock is permanent for a txid (DIP-0010) and // trust only ever settles, so both latch monotonically. A - // coin reservation is orthogonal to chain context and is kept - // as-is. `is_confirmed` stays freshly derived so a reorg can - // still downgrade it. + // coin lock follows the wallet's lock set, not chain context, + // and is kept as-is. `is_confirmed` stays freshly derived so a + // reorg can still downgrade it. if let Some(prior) = self.utxos.get(&outpoint) { utxo.is_instantlocked |= prior.is_instantlocked; utxo.is_trusted |= prior.is_trusted; diff --git a/key-wallet/src/tests/balance_tests.rs b/key-wallet/src/tests/balance_tests.rs index ecb1f1481..d0cd4cb83 100644 --- a/key-wallet/src/tests/balance_tests.rs +++ b/key-wallet/src/tests/balance_tests.rs @@ -54,13 +54,18 @@ fn test_locked_utxos_in_locked_balance() { let mut wallet_info = ManagedWalletInfo::dummy(3); let mut account = ManagedCoreFundsAccount::dummy_bip44(); - let mut utxo = Utxo::dummy(1, 100_000, 1000, false, true); - utxo.is_locked = true; + let utxo = Utxo::dummy(1, 100_000, 1000, false, true); + let outpoint = utxo.outpoint; account.utxos.insert(utxo.outpoint, utxo); wallet_info.accounts.insert(account).unwrap(); assert_eq!(wallet_info.balance, WalletCoreBalance::default()); wallet_info.update_last_processed_height(1100); + assert_eq!(wallet_info.balance, WalletCoreBalance::new(100_000, 0, 0, 0)); + + // A held coin is locked through the wallet's lock set, which moves its + // value to the locked bucket. + assert!(wallet_info.lock_outpoint(outpoint)); let expected = WalletCoreBalance::new(0, 0, 0, 100_000); assert_eq!(wallet_info.balance, expected); } diff --git a/key-wallet/src/tests/locked_outpoints_tests.rs b/key-wallet/src/tests/locked_outpoints_tests.rs new file mode 100644 index 000000000..4bd2d294c --- /dev/null +++ b/key-wallet/src/tests/locked_outpoints_tests.rs @@ -0,0 +1,582 @@ +//! A wallet locks the coins it owns that back a registered masternode, so +//! ordinary sends never spend them, and anything else locked by hand. See +//! [`ManagedWalletInfo::locked_outpoints`](crate::wallet::ManagedWalletInfo::locked_outpoints). + +use std::str::FromStr; + +use dashcore::address::NetworkUnchecked; +use dashcore::blockdata::transaction::special_transaction::provider_registration::{ + ProviderMasternodeType, ProviderRegistrationPayload, +}; +use dashcore::blockdata::transaction::special_transaction::provider_update_revocation::ProviderUpdateRevocationPayload; +use dashcore::blockdata::transaction::special_transaction::provider_update_service::ProviderUpdateServicePayload; +use dashcore::blockdata::transaction::special_transaction::TransactionPayload; +use dashcore::bls_sig_utils::{BLSPublicKey, BLSSignature}; +use dashcore::hash_types::InputsHash; +use dashcore::hashes::Hash; +use dashcore::{ + Address, BlockHash, OutPoint, PubkeyHash, ScriptBuf, Transaction, TxIn, TxOut, Txid, +}; +use test_case::test_case; + +use crate::test_utils::TestWalletContext; +use crate::transaction_checking::{BlockInfo, TransactionContext, WalletTransactionChecker}; +use crate::wallet::managed_wallet_info::asset_lock_builder::{ + AssetLockError, AssetLockFundingType, CreditOutputFunding, +}; +use crate::wallet::managed_wallet_info::coin_selection::{SelectionError, SelectionStrategy}; +use crate::wallet::managed_wallet_info::fee::FeeRate; +use crate::wallet::managed_wallet_info::transaction_builder::{BuilderError, TransactionBuilder}; +use crate::wallet::managed_wallet_info::transaction_building::AccountTypePreference; +use crate::wallet::managed_wallet_info::wallet_info_interface::WalletInfoInterface; +use crate::Utxo; + +const DASH: u64 = 100_000_000; +const COLLATERAL: u64 = 1_000 * DASH; +const SPARE: u64 = 5 * DASH; +const TIP: u32 = 200; + +fn block(height: u32) -> TransactionContext { + TransactionContext::InBlock(BlockInfo::new( + height, + BlockHash::from_byte_array([height as u8; 32]), + 1_700_000_000 + height, + )) +} + +/// An address that is not the wallet's. +fn elsewhere() -> Address { + Address::from_str("yTb47qEBpNmgXvYYsHEN4nh8yJwa5iC4Cs").expect("testnet address") +} + +/// A ProRegTx registering `collateral`, paying `outputs`. Everything else, +/// its fee input and keys included, belongs to no one this wallet knows, so +/// the collateral is its only link to the wallet. `seed` varies the txid. +fn registration(collateral: OutPoint, outputs: Vec, seed: u8) -> Transaction { + let key_hash = PubkeyHash::from_byte_array([0x70; 20]); + Transaction { + version: 3, + lock_time: 0, + input: vec![TxIn { + previous_output: OutPoint::new(Txid::from_byte_array([seed; 32]), 0), + ..Default::default() + }], + output: outputs, + special_transaction_payload: Some(TransactionPayload::ProviderRegistrationPayloadType( + ProviderRegistrationPayload { + version: 1, + masternode_type: ProviderMasternodeType::Regular, + masternode_mode: 0, + collateral_outpoint: collateral, + service_address: "127.0.0.1:19999".parse().expect("socket address"), + owner_key_hash: key_hash, + operator_public_key: BLSPublicKey::from([0x11; 48]), + voting_key_hash: key_hash, + operator_reward: 0, + script_payout: ScriptBuf::new(), + inputs_hash: InputsHash::all_zeros(), + signature: vec![0x33; 65], + platform_node_id: None, + platform_p2p_port: None, + platform_http_port: None, + }, + )), + } +} + +/// Pay `value` to the wallet in a block at `height`; `seed` varies the txid. +async fn receive(ctx: &mut TestWalletContext, value: u64, seed: u8, height: u32) -> OutPoint { + let tx = Transaction::dummy(&ctx.receive_address, seed..seed + 1, &[value]); + assert!(ctx.check_transaction(&tx, block(height)).await.is_relevant); + OutPoint::new(tx.txid(), 0) +} + +/// A wallet holding a 1,000 DASH coin registered as masternode collateral by +/// a ProRegTx it has seen, and a spare coin of `spare` duffs, if any. +async fn registered_wallet(spare: Option) -> (TestWalletContext, OutPoint, Option) { + let mut ctx = TestWalletContext::new_random(); + let collateral = receive(&mut ctx, COLLATERAL, 0x01, 100).await; + let spare = match spare { + Some(value) => Some(receive(&mut ctx, value, 0x02, 100).await), + None => None, + }; + let registration = registration(collateral, vec![], 0xEE); + let registered = ctx.check_transaction(®istration, block(101)).await; + assert_eq!(registered.locked_outpoints, vec![collateral]); + ctx.managed_wallet.update_last_processed_height(TIP); + (ctx, collateral, spare) +} + +/// Build a send of `amount` from BIP44 account 0 without signing it. The +/// build's reservation is handed back, so the next build sees every coin. +fn send( + ctx: &mut TestWalletContext, + amount: u64, + strategy: SelectionStrategy, +) -> Result { + let (tx, _fee) = ctx.managed_wallet.build_unsigned_transaction( + &ctx.wallet, + &[AccountTypePreference::BIP44], + 0, + vec![(elsewhere(), amount)], + FeeRate::normal(), + strategy, + )?; + ctx.bip44_account().release_reservation(&tx); + Ok(tx) +} + +fn spent(tx: &Transaction) -> Vec { + tx.input.iter().map(|input| input.previous_output).collect() +} + +fn is_out_of_coins(result: Result) -> bool { + matches!( + result, + Err(BuilderError::CoinSelection( + SelectionError::NoUtxosAvailable + | SelectionError::InsufficientFunds { + available: 0, + .. + } + )) + ) +} + +#[test_case(SelectionStrategy::SmallestFirst ; "smallest first")] +#[test_case(SelectionStrategy::LargestFirst ; "largest first")] +#[test_case(SelectionStrategy::SmallestFirstTill(1) ; "smallest first till one")] +#[test_case(SelectionStrategy::BranchAndBound ; "branch and bound")] +#[test_case(SelectionStrategy::OptimalConsolidation ; "optimal consolidation")] +#[test_case(SelectionStrategy::Random ; "random")] +#[test_case(SelectionStrategy::All ; "drain")] +#[tokio::test] +async fn a_send_spends_the_spare_coin_and_never_the_collateral(strategy: SelectionStrategy) { + let (mut ctx, _collateral, spare) = registered_wallet(Some(SPARE)).await; + + let tx = send(&mut ctx, DASH, strategy).expect("the spare 5 DASH covers a 1 DASH send"); + + // A drain takes every spendable coin: still only the spare one. + assert_eq!(spent(&tx), vec![spare.expect("spare coin")]); +} + +#[test_case(SelectionStrategy::SmallestFirst ; "smallest first")] +#[test_case(SelectionStrategy::LargestFirst ; "largest first")] +#[test_case(SelectionStrategy::SmallestFirstTill(1) ; "smallest first till one")] +#[test_case(SelectionStrategy::BranchAndBound ; "branch and bound")] +#[test_case(SelectionStrategy::OptimalConsolidation ; "optimal consolidation")] +#[test_case(SelectionStrategy::Random ; "random")] +#[test_case(SelectionStrategy::All ; "drain")] +#[tokio::test] +async fn a_wallet_holding_only_its_collateral_has_nothing_to_send(strategy: SelectionStrategy) { + let (mut ctx, _collateral, _) = registered_wallet(None).await; + + assert!(is_out_of_coins(send(&mut ctx, DASH, strategy))); + assert!(ctx.managed_wallet.get_spendable_utxos().is_empty()); + let balance = ctx.managed_wallet.balance(); + assert_eq!(balance.spendable(), 0, "the collateral is not spendable balance"); + assert_eq!(balance.locked(), COLLATERAL); + assert_eq!(balance.total(), COLLATERAL, "the collateral still counts toward the total"); +} + +/// The lock comes from the registration, not the amount: the same 1,000 DASH +/// coin is an ordinary coin until a ProRegTx names it. +#[tokio::test] +async fn a_collateral_sized_coin_nobody_registered_is_spendable() { + let mut ctx = TestWalletContext::new_random(); + let big = receive(&mut ctx, COLLATERAL, 0x01, 100).await; + receive(&mut ctx, SPARE, 0x02, 100).await; + ctx.managed_wallet.update_last_processed_height(TIP); + + let tx = send(&mut ctx, DASH, SelectionStrategy::LargestFirst).expect("funded"); + + assert_eq!(spent(&tx), vec![big]); + assert!(ctx.managed_wallet.locked_outpoints().is_empty()); +} + +#[test_case(true ; "collateral first")] +#[test_case(false ; "registration first")] +#[tokio::test] +async fn a_registration_locks_its_external_collateral_whichever_arrives_first( + collateral_first: bool, +) { + let mut ctx = TestWalletContext::new_random(); + let collateral_tx = Transaction::dummy(&ctx.receive_address, 0x01..0x02, &[COLLATERAL]); + let collateral = OutPoint::new(collateral_tx.txid(), 0); + let registration = registration(collateral, vec![], 0xEE); + + let registered = if collateral_first { + ctx.check_transaction(&collateral_tx, block(100)).await; + ctx.check_transaction(®istration, block(101)).await + } else { + // A rescan can hand over the later block first. + let registered = ctx.check_transaction(®istration, block(101)).await; + assert!(ctx.managed_wallet.is_outpoint_locked(&collateral), "locked before it arrives"); + ctx.check_transaction(&collateral_tx, block(100)).await; + registered + }; + + // No separate balance refresh: the checks leave the balance right. + assert!(!registered.is_relevant, "nothing but the collateral ties it to this wallet"); + assert_eq!(registered.locked_outpoints, vec![collateral]); + assert!(registered.state_modified, "the lock set is persisted state"); + assert!(ctx.bip44_account().utxos[&collateral].is_locked); + assert_eq!(ctx.managed_wallet.balance().locked(), COLLATERAL); + assert!(is_out_of_coins(send(&mut ctx, DASH, SelectionStrategy::LargestFirst))); +} + +#[test_case(&[TransactionContext::Mempool, block(101)] ; "seen in the mempool, then mined")] +#[test_case(&[block(101)] ; "first seen mined")] +#[tokio::test] +async fn a_registration_locks_the_collateral_it_creates(sightings: &[TransactionContext]) { + let mut ctx = TestWalletContext::new_random(); + let to_wallet = TxOut { + value: COLLATERAL, + script_pubkey: ctx.receive_address.script_pubkey(), + }; + let to_elsewhere = TxOut { + value: DASH, + script_pubkey: elsewhere().assume_checked().script_pubkey(), + }; + // A null collateral txid: the collateral is this ProRegTx's output 1. + let registration = + registration(OutPoint::new(Txid::all_zeros(), 1), vec![to_elsewhere, to_wallet], 0xEE); + let collateral = OutPoint::new(registration.txid(), 1); + + let mut reported = Vec::new(); + for context in sightings { + let result = ctx.check_transaction(®istration, context.clone()).await; + assert!(result.is_relevant, "the collateral pays this wallet"); + reported.extend(result.locked_outpoints); + assert!( + ctx.bip44_account().utxos[&collateral].is_locked, + "the coin is locked from its first sighting, in {context}" + ); + } + ctx.managed_wallet.update_last_processed_height(TIP); + + assert_eq!(reported, vec![collateral], "reported once, when first locked"); + assert_eq!(ctx.managed_wallet.balance().locked(), COLLATERAL); + assert!(is_out_of_coins(send(&mut ctx, DASH, SelectionStrategy::LargestFirst))); +} + +#[tokio::test] +async fn unlocking_lets_a_send_spend_the_collateral_and_relocking_stops_it_again() { + let (mut ctx, collateral, _) = registered_wallet(None).await; + assert!(is_out_of_coins(send(&mut ctx, DASH, SelectionStrategy::LargestFirst))); + + assert!(ctx.managed_wallet.unlock_outpoint(&collateral)); + assert!(!ctx.managed_wallet.unlock_outpoint(&collateral), "already unlocked"); + assert_eq!(ctx.managed_wallet.balance().spendable(), COLLATERAL); + assert_eq!(ctx.managed_wallet.balance().locked(), 0); + let tx = send(&mut ctx, DASH, SelectionStrategy::LargestFirst).expect("unlocked"); + assert_eq!(spent(&tx), vec![collateral]); + + assert!(ctx.managed_wallet.lock_outpoint(collateral)); + assert!(!ctx.managed_wallet.lock_outpoint(collateral), "already locked"); + assert_eq!(ctx.managed_wallet.balance().locked(), COLLATERAL); + assert!(is_out_of_coins(send(&mut ctx, DASH, SelectionStrategy::LargestFirst))); +} + +/// Core ties the lock to the masternode list, which only spending the +/// collateral leaves: a revocation keeps the masternode registered, and a new +/// ProRegTx naming the same collateral replaces the registration. +#[tokio::test] +async fn a_revocation_or_a_replacing_registration_keeps_the_collateral_locked() { + let (mut ctx, collateral, spare) = registered_wallet(Some(SPARE)).await; + let original = registration(collateral, vec![], 0xEE); + + let revocation = Transaction { + version: 3, + lock_time: 0, + input: vec![TxIn { + previous_output: OutPoint::new(Txid::from_byte_array([0xEF; 32]), 0), + ..Default::default() + }], + output: Vec::new(), + special_transaction_payload: Some(TransactionPayload::ProviderUpdateRevocationPayloadType( + ProviderUpdateRevocationPayload { + version: 1, + pro_tx_hash: original.txid(), + reason: 0, + inputs_hash: InputsHash::all_zeros(), + payload_sig: BLSSignature::from([0; 96]), + }, + )), + }; + assert!(ctx.check_transaction(&revocation, block(102)).await.locked_outpoints.is_empty()); + assert!(ctx.managed_wallet.is_outpoint_locked(&collateral)); + + let replacement = registration(collateral, vec![], 0xF0); + let replaced = ctx.check_transaction(&replacement, block(103)).await; + assert!(replaced.locked_outpoints.is_empty(), "already locked, nothing new to report"); + assert!(ctx.managed_wallet.is_outpoint_locked(&collateral)); + + ctx.managed_wallet.update_last_processed_height(TIP); + let tx = send(&mut ctx, DASH, SelectionStrategy::LargestFirst).expect("the spare coin"); + assert_eq!(spent(&tx), vec![spare.expect("spare coin")]); +} + +/// Only spending the collateral ends a registration. The coin leaves; its +/// entry stays and has nothing to act on, so a spend that is reorged out or +/// swept brings the coin back locked. +#[tokio::test] +async fn spending_the_collateral_removes_the_coin_but_not_its_lock() { + let (mut ctx, collateral, _) = registered_wallet(None).await; + let spend = Transaction { + version: 1, + lock_time: 0, + input: vec![TxIn { + previous_output: collateral, + ..Default::default() + }], + output: vec![TxOut { + value: COLLATERAL - 1_000, + script_pubkey: elsewhere().assume_checked().script_pubkey(), + }], + special_transaction_payload: None, + }; + + assert!(ctx.check_transaction(&spend, block(150)).await.is_relevant); + + assert!(!ctx.bip44_account().utxos.contains_key(&collateral)); + assert!(ctx.managed_wallet.is_outpoint_locked(&collateral)); + assert_eq!(ctx.managed_wallet.balance().total(), 0); +} + +#[tokio::test] +async fn a_preview_check_locks_nothing() { + let mut ctx = TestWalletContext::new_random(); + let collateral = receive(&mut ctx, COLLATERAL, 0x01, 100).await; + + let preview = ctx + .managed_wallet + .check_core_transaction( + ®istration(collateral, vec![], 0xEE), + block(101), + &mut ctx.wallet, + false, + false, + ) + .await; + + assert!(preview.locked_outpoints.is_empty()); + assert!(!ctx.managed_wallet.is_outpoint_locked(&collateral)); + assert!(!ctx.bip44_account().utxos[&collateral].is_locked); +} + +/// Block processing checks each transaction with `update_balance = false` and +/// refreshes the balance once per block. The coin must be locked in between, +/// not only after that refresh. +#[tokio::test] +async fn a_collateral_is_locked_even_before_the_next_balance_refresh() { + let mut ctx = TestWalletContext::new_random(); + let collateral = receive(&mut ctx, COLLATERAL, 0x01, 100).await; + + let result = ctx + .managed_wallet + .check_core_transaction( + ®istration(collateral, vec![], 0xEE), + block(101), + &mut ctx.wallet, + true, + false, + ) + .await; + + assert_eq!(result.locked_outpoints, vec![collateral]); + assert!(ctx.bip44_account().utxos[&collateral].is_locked); + assert!(ctx.managed_wallet.get_spendable_utxos().is_empty()); +} + +/// The lock set is the source of truth: a flag written on a held coin by hand +/// is set back from the set on the next balance refresh. +#[tokio::test] +async fn a_held_coins_lock_flag_follows_the_lock_set() { + let (mut ctx, collateral, spare) = registered_wallet(Some(SPARE)).await; + let spare = spare.expect("spare coin"); + let account = ctx.managed_wallet.first_bip44_managed_account_mut().expect("BIP44 account"); + account.utxos.get_mut(&collateral).expect("collateral").is_locked = false; + account.utxos.get_mut(&spare).expect("spare").is_locked = true; + + ctx.managed_wallet.update_balance(); + + assert!(ctx.bip44_account().utxos[&collateral].is_locked); + assert!(!ctx.bip44_account().utxos[&spare].is_locked); + assert_eq!(ctx.managed_wallet.balance().locked(), COLLATERAL); + assert_eq!(ctx.managed_wallet.balance().spendable(), SPARE); +} + +#[test_case(false ; "a set amount")] +#[test_case(true ; "a drain")] +#[tokio::test] +async fn the_asset_lock_builder_skips_the_collateral(drain: bool) { + let (mut ctx, _collateral, spare) = registered_wallet(Some(SPARE)).await; + let credit = CreditOutputFunding { + output: TxOut { + value: DASH, + script_pubkey: elsewhere().assume_checked().script_pubkey(), + }, + funding_type: AssetLockFundingType::AssetLockAddressTopUp, + identity_index: 0, + }; + + let built = ctx + .managed_wallet + .build_asset_lock( + &ctx.wallet, + &[AccountTypePreference::BIP44], + 0, + vec![credit], + 1000, + drain, + ) + .await + .expect("the spare coin funds the asset lock"); + + assert_eq!(spent(&built.transaction), vec![spare.expect("spare coin")]); +} + +#[tokio::test] +async fn the_asset_lock_builder_has_nothing_to_lock_from_the_collateral_alone() { + let (mut ctx, _collateral, _) = registered_wallet(None).await; + let credit = CreditOutputFunding { + output: TxOut { + value: DASH, + script_pubkey: elsewhere().assume_checked().script_pubkey(), + }, + funding_type: AssetLockFundingType::AssetLockAddressTopUp, + identity_index: 0, + }; + + let built = ctx + .managed_wallet + .build_asset_lock(&ctx.wallet, &[AccountTypePreference::BIP44], 0, vec![credit], 1000, true) + .await; + + assert!( + matches!( + built, + Err(AssetLockError::Builder(BuilderError::CoinSelection( + SelectionError::NoUtxosAvailable + ))) + ), + "only the collateral is left, and it is locked" + ); +} + +/// A ProUpServTx placeholder: special transactions such as provider updates +/// fund their fee through `add_funding`. +fn provider_update_service() -> TransactionPayload { + TransactionPayload::ProviderUpdateServicePayloadType(ProviderUpdateServicePayload::new( + Some(0), + Txid::all_zeros(), + 0x00000000000000000000ffff7f000001, // 127.0.0.1 mapped + 19999, + ScriptBuf::new(), + InputsHash::all_zeros(), + None, + None, + None, + BLSSignature::from([0; 96]), + )) +} + +/// A copy of the collateral cloned before it was locked, or built by the +/// caller, still carries an unlocked flag. +fn stale_copy(ctx: &TestWalletContext, collateral: OutPoint) -> Utxo { + let mut stale = ctx.bip44_account().utxos[&collateral].clone(); + stale.is_locked = false; + stale +} + +#[tokio::test] +async fn special_transaction_funding_skips_the_collateral_even_when_seeded() { + let (mut ctx, collateral, spare) = registered_wallet(Some(SPARE)).await; + let stale = stale_copy(&ctx, collateral); + let account = ctx.wallet.accounts.standard_bip44_accounts.get(&0).expect("BIP44").clone(); + let funds = ctx.managed_wallet.accounts.standard_bip44_accounts.get_mut(&0).expect("BIP44"); + + let (tx, _fee, _reservation) = TransactionBuilder::new() + .set_current_height(TIP) + .set_fee_rate(FeeRate::normal()) + .add_inputs([stale]) + .add_funding(funds, &account) + .set_special_payload(provider_update_service()) + .build_unsigned_reserved() + .expect("the spare coin pays the fee"); + + assert_eq!(spent(&tx), vec![spare.expect("spare coin")]); +} + +/// The chunked drain path offers only what the caller seeds; a seeded copy of +/// a coin the account holds locked is dropped all the same. +#[tokio::test] +async fn reservation_only_funding_drops_a_seeded_collateral() { + let (mut ctx, collateral, _) = registered_wallet(None).await; + let stale = stale_copy(&ctx, collateral); + let account = ctx.wallet.accounts.standard_bip44_accounts.get(&0).expect("BIP44").clone(); + let funds = ctx.managed_wallet.accounts.standard_bip44_accounts.get_mut(&0).expect("BIP44"); + + let result = TransactionBuilder::new() + .set_current_height(TIP) + .set_selection_strategy(SelectionStrategy::All) + .add_inputs([stale]) + .add_funding_reservation_only(funds, &account) + .add_output(&elsewhere().assume_checked(), DASH) + .build_unsigned_reserved(); + + assert!(matches!(result, Err(BuilderError::CoinSelection(SelectionError::NoUtxosAvailable)))); +} + +#[cfg(feature = "serde")] +#[test] +fn locks_survive_a_serialization_round_trip() { + use crate::managed_account::ManagedCoreFundsAccount; + use crate::wallet::ManagedWalletInfo; + + let mut info = ManagedWalletInfo::dummy(1); + let mut account = ManagedCoreFundsAccount::dummy_bip44(); + let collateral = Utxo::dummy(1, COLLATERAL, 100, false, true); + let spare = Utxo::dummy(2, SPARE, 100, false, true); + account.utxos.insert(collateral.outpoint, collateral.clone()); + account.utxos.insert(spare.outpoint, spare.clone()); + info.accounts.insert(account).expect("account"); + // Locked before the coin arrives, as when a registration is seen first. + let arriving = Utxo::dummy(3, COLLATERAL, 100, false, true); + info.lock_outpoint(collateral.outpoint); + info.lock_outpoint(arriving.outpoint); + + let json = serde_json::to_string(&info).expect("serialize"); + let mut restored: ManagedWalletInfo = serde_json::from_str(&json).expect("deserialize"); + + assert_eq!(restored.locked_outpoints(), info.locked_outpoints()); + restored.update_last_processed_height(TIP); + let spendable: Vec = + restored.get_spendable_utxos().into_iter().map(|utxo| utxo.outpoint).collect(); + assert_eq!(spendable, vec![spare.outpoint]); + assert_eq!(restored.balance().locked(), COLLATERAL); + + // The lock taken before the coin arrived still applies after the reload. + let account = restored.first_bip44_managed_account_mut().expect("BIP44 account"); + account.utxos.insert(arriving.outpoint, arriving.clone()); + restored.update_balance(); + assert_eq!(restored.balance().locked(), 2 * COLLATERAL); + assert_eq!(restored.balance().spendable(), SPARE); +} + +/// A snapshot written before the lock set existed loads with no locks. +#[cfg(feature = "serde")] +#[test] +fn a_snapshot_without_locks_loads_with_none() { + use crate::wallet::ManagedWalletInfo; + + let mut info = ManagedWalletInfo::dummy(2); + info.lock_outpoint(OutPoint::new(Txid::from_byte_array([0x42; 32]), 0)); + let mut json = serde_json::to_value(&info).expect("serialize"); + json.as_object_mut().expect("object").remove("locked_outpoints").expect("the field"); + + let restored: ManagedWalletInfo = serde_json::from_value(json).expect("deserialize"); + + assert!(restored.locked_outpoints().is_empty()); +} diff --git a/key-wallet/src/tests/mod.rs b/key-wallet/src/tests/mod.rs index 6b490d4ab..f3484a09c 100644 --- a/key-wallet/src/tests/mod.rs +++ b/key-wallet/src/tests/mod.rs @@ -22,6 +22,8 @@ mod integration_tests; mod keep_finalized_transactions_tests; +mod locked_outpoints_tests; + mod managed_account_collection_tests; mod observed_spent_outpoints_tests; diff --git a/key-wallet/src/transaction_checking/account_checker.rs b/key-wallet/src/transaction_checking/account_checker.rs index 5f4183a0b..e3a23bd51 100644 --- a/key-wallet/src/transaction_checking/account_checker.rs +++ b/key-wallet/src/transaction_checking/account_checker.rs @@ -101,6 +101,16 @@ pub struct TransactionCheckResult { /// [`ManagedCoreFundsAccount::drop_conflicted_transactions`]: /// crate::managed_account::ManagedCoreFundsAccount pub released_outpoints: Vec, + /// Outpoints this check added to the wallet's lock set: the collateral of + /// a ProRegTx, which coin selection now skips. Only new entries are + /// listed, so a ProRegTx seen again reports nothing. + /// + /// Filled whether or not the transaction is otherwise relevant: the + /// registration may involve nothing of this wallet's but the collateral, + /// or the collateral may not have arrived yet. A store that persists + /// wallet state records these; see + /// [`ManagedWalletInfo::locked_outpoints`](crate::wallet::ManagedWalletInfo::locked_outpoints). + pub locked_outpoints: Vec, } /// Enum representing the type of Core account that matched with embedded data @@ -432,6 +442,7 @@ impl ManagedAccountCollection { updated_records: Vec::new(), swept_transactions: Vec::new(), released_outpoints: Vec::new(), + locked_outpoints: Vec::new(), }; for account_type in account_types { diff --git a/key-wallet/src/transaction_checking/wallet_checker.rs b/key-wallet/src/transaction_checking/wallet_checker.rs index 81f1adf1b..3e2b9af5c 100644 --- a/key-wallet/src/transaction_checking/wallet_checker.rs +++ b/key-wallet/src/transaction_checking/wallet_checker.rs @@ -11,7 +11,7 @@ use crate::wallet::managed_wallet_info::ManagedWalletInfo; use crate::{KeySource, Wallet}; use async_trait::async_trait; use dashcore::blockdata::transaction::Transaction; -use dashcore::{Amount, SignedAmount}; +use dashcore::{Amount, OutPoint, SignedAmount}; /// Extension trait for ManagedWalletInfo to add transaction checking capabilities #[async_trait] @@ -31,6 +31,10 @@ pub trait WalletTransactionChecker { /// /// The context parameter indicates where the transaction comes from (mempool, block, etc.) /// + /// With `update_state`, a ProRegTx also locks the collateral it + /// registers, relevant or not, so coin selection skips it; new locks are + /// listed in [`TransactionCheckResult::locked_outpoints`]. See + /// [`ManagedWalletInfo::locked_outpoints`]. async fn check_core_transaction( &mut self, tx: &Transaction, @@ -112,6 +116,55 @@ impl WalletTransactionChecker for ManagedWalletInfo { wallet: &mut Wallet, update_state: bool, update_balance: bool, + ) -> TransactionCheckResult { + if !update_state { + return self + .check_core_transaction_inner(tx, context, wallet, update_state, update_balance) + .await; + } + + // Before the accounts record `tx`, so a collateral the ProRegTx + // creates itself is locked from the moment it becomes a coin. + let collateral = self.lock_masternode_collateral(tx); + + let mut result = self + .check_core_transaction_inner(tx, context, wallet, update_state, update_balance) + .await; + + // Bring the lock flags of the coins involved in line with the lock + // set: the coins `tx` pays this wallet, and a collateral the wallet + // already held. The balance refresh inside the check does this when it + // runs, but not every path reaches one: an otherwise irrelevant + // ProRegTx returns early, and block processing passes + // `update_balance = false` and refreshes once per block. + let txid = tx.txid(); + let outputs = (0..tx.output.len() as u32).map(|vout| OutPoint::new(txid, vout)); + let flags_changed = self.refresh_lock_flags(outputs.chain(collateral)); + + if let Some(collateral) = collateral { + result.locked_outpoints.push(collateral); + // The lock set is persisted wallet state. + result.state_modified = true; + } + if flags_changed && update_balance { + self.update_balance(); + } + + result + } +} + +impl ManagedWalletInfo { + /// Everything [`WalletTransactionChecker::check_core_transaction`] does + /// except keeping coin locks: the caller locks a ProRegTx's collateral and + /// refreshes the lock flags around it. + async fn check_core_transaction_inner( + &mut self, + tx: &Transaction, + context: TransactionContext, + wallet: &mut Wallet, + update_state: bool, + update_balance: bool, ) -> TransactionCheckResult { // Classify the transaction let tx_type = TransactionRouter::classify_transaction(tx); diff --git a/key-wallet/src/utxo.rs b/key-wallet/src/utxo.rs index 5672f85be..bc520a888 100644 --- a/key-wallet/src/utxo.rs +++ b/key-wallet/src/utxo.rs @@ -30,7 +30,12 @@ pub struct Utxo { pub is_confirmed: bool, /// Whether this UTXO has an InstantLock pub is_instantlocked: bool, - /// Whether this UTXO is locked (not available for spending) + /// Whether this UTXO is locked: coin selection skips it and its value + /// counts as locked balance. + /// + /// For a coin a wallet holds, the wallet sets this from its lock set, + /// [`ManagedWalletInfo::locked_outpoints`](crate::wallet::ManagedWalletInfo::locked_outpoints), + /// which is where such a coin is locked and unlocked. pub is_locked: bool, /// Whether this UTXO comes from a "trusted" mempool transaction — one we /// created ourselves, recognised because it spends at least one of our @@ -100,12 +105,21 @@ impl Utxo { } } - /// Lock this UTXO to prevent it from being selected + /// Lock this UTXO to prevent it from being selected. + /// + /// For a coin outside a wallet, such as one handed to a transaction + /// builder. A wallet overwrites the flag of a coin it holds from its lock + /// set: lock that coin with + /// [`ManagedWalletInfo::lock_outpoint`](crate::wallet::ManagedWalletInfo::lock_outpoint). pub fn lock(&mut self) { self.is_locked = true; } - /// Unlock this UTXO to allow it to be selected + /// Unlock this UTXO to allow it to be selected. + /// + /// For a coin outside a wallet, as with [`Self::lock`]. Unlock a coin a + /// wallet holds with + /// [`ManagedWalletInfo::unlock_outpoint`](crate::wallet::ManagedWalletInfo::unlock_outpoint). pub fn unlock(&mut self) { self.is_locked = false; } diff --git a/key-wallet/src/wallet/balance.rs b/key-wallet/src/wallet/balance.rs index 063700bfa..761daf1bf 100644 --- a/key-wallet/src/wallet/balance.rs +++ b/key-wallet/src/wallet/balance.rs @@ -23,7 +23,8 @@ pub struct WalletCoreBalance { unconfirmed: u64, /// Immature balance (UTXOs without enough confirmations for maturity, e.g. 100 for coinbase). immature: u64, - /// Locked balance (UTXOs reserved for specific purposes like CoinJoin). + /// Locked balance: coins the wallet will not spend, such as masternode + /// collateral (see `ManagedWalletInfo::locked_outpoints`). locked: u64, } diff --git a/key-wallet/src/wallet/managed_wallet_info/locked_outpoints.rs b/key-wallet/src/wallet/managed_wallet_info/locked_outpoints.rs new file mode 100644 index 000000000..8a5da617b --- /dev/null +++ b/key-wallet/src/wallet/managed_wallet_info/locked_outpoints.rs @@ -0,0 +1,255 @@ +//! Outpoints the wallet will not spend. +//! +//! The wallet keeps one set of locked outpoints, like Dash Core's +//! `setLockedCoins`, and coin selection never spends a coin in it. A ProRegTx +//! locks the collateral it registers; [`ManagedWalletInfo::lock_outpoint`] and +//! [`ManagedWalletInfo::unlock_outpoint`] lock and unlock anything by hand. See +//! [`ManagedWalletInfo::locked_outpoints`] for the full rules. + +use super::ManagedWalletInfo; +use crate::wallet::managed_wallet_info::wallet_info_interface::WalletInfoInterface; +use dashcore::blockdata::transaction::special_transaction::TransactionPayload; +use dashcore::hashes::Hash; +use dashcore::{OutPoint, Transaction, Txid}; +use std::collections::BTreeSet; + +/// The collateral `tx` registers when it is a ProRegTx, `None` otherwise. +/// +/// A null collateral txid means the ProRegTx creates its collateral itself, as +/// its own output at `collateralIndex`. An index past its outputs names no coin +/// (Core rejects such a registration), so it yields `None`. +pub(crate) fn masternode_collateral(tx: &Transaction) -> Option { + let Some(TransactionPayload::ProviderRegistrationPayloadType(registration)) = + &tx.special_transaction_payload + else { + return None; + }; + let named = registration.collateral_outpoint; + if named.txid != Txid::all_zeros() { + return Some(named); + } + ((named.vout as usize) < tx.output.len()).then(|| OutPoint::new(tx.txid(), named.vout)) +} + +impl ManagedWalletInfo { + /// The outpoints this wallet will not spend. + /// + /// Coin selection never picks a coin whose outpoint is in this set, for any + /// [`SelectionStrategy`](crate::wallet::managed_wallet_info::coin_selection::SelectionStrategy), + /// the `All` drain included, and such a coin counts toward + /// [`WalletCoreBalance::locked`](crate::WalletCoreBalance::locked) rather + /// than the spendable balance. + /// + /// # What locks an outpoint + /// + /// - A ProRegTx. The wallet locks the collateral of every masternode + /// registration it processes, so an ordinary send never spends it: + /// spending the collateral would end the registration. The collateral is + /// the ProRegTx's `collateralOutpoint`, or, when that names a null txid, + /// the ProRegTx's own output at `collateralIndex`. + /// - [`Self::lock_outpoint`]. + /// + /// Only [`Self::unlock_outpoint`] removes an outpoint. A coin's amount is + /// never a reason to lock it. + /// + /// # Order does not matter + /// + /// An entry does not need a coin behind it. A collateral seen after its + /// ProRegTx, or a coin locked before it arrives, arrives locked. A ProRegTx + /// naming a coin that is not this wallet's leaves an entry that never + /// matches anything. + /// + /// # How long a lock lasts + /// + /// Until [`Self::unlock_outpoint`]. Dash Core ties the collateral lock to + /// its masternode list: a ProUpRevTx leaves the masternode registered, so + /// the collateral stays locked; a later ProRegTx naming the same collateral + /// replaces the registration and keeps it locked; only spending the + /// collateral ends the registration. Core then drops the lock along with + /// the coin, and re-derives it from its masternode list whenever the coin + /// could come back (on load, and when the spend is abandoned). An SPV + /// wallet has no masternode list, so it keeps the entry instead: once the + /// coin is spent the entry has nothing to act on, and a coin whose spend is + /// reorged out or swept comes back locked. + /// + /// Processing a ProRegTx again (the block that confirms it, a rescan) locks + /// its collateral again, as Core does on load. + /// + /// # The set is the source of truth + /// + /// Coin selection works on [`Utxo`](crate::Utxo)s and skips a locked one + /// through [`Utxo::is_spendable`](crate::Utxo::is_spendable). The wallet + /// keeps the `is_locked` flag of every coin it holds equal to membership in + /// this set: when the coin arrives, when its outpoint is locked or + /// unlocked, and on every balance refresh. A flag written on a held coin + /// directly is overwritten by the next refresh. + /// + /// # Persistence + /// + /// The set is serialized with the wallet. A store that keeps wallet state + /// some other way persists this set instead: the outpoints a transaction + /// check locks arrive on + /// [`TransactionCheckResult::locked_outpoints`](crate::transaction_checking::TransactionCheckResult::locked_outpoints), + /// [`Self::lock_outpoint`] and [`Self::unlock_outpoint`] report their own + /// changes, and on load the store calls [`Self::lock_outpoint`] for each + /// persisted outpoint, before or after restoring the coins. + pub fn locked_outpoints(&self) -> &BTreeSet { + &self.locked_outpoints + } + + /// Whether `outpoint` is locked. See [`Self::locked_outpoints`]. + pub fn is_outpoint_locked(&self, outpoint: &OutPoint) -> bool { + self.locked_outpoints.contains(outpoint) + } + + /// Lock `outpoint`, so coin selection does not spend it until + /// [`Self::unlock_outpoint`]. See [`Self::locked_outpoints`]. + /// + /// The wallet does not need to hold the coin yet: it arrives locked. + /// Returns `true` when the outpoint was not locked before. When the wallet + /// holds the coin, its value moves to the locked balance. + pub fn lock_outpoint(&mut self, outpoint: OutPoint) -> bool { + if !self.locked_outpoints.insert(outpoint) { + return false; + } + if self.refresh_lock_flags([outpoint]) { + self.update_balance(); + } + true + } + + /// Unlock `outpoint`, so coin selection may spend it again. See + /// [`Self::locked_outpoints`]. + /// + /// Unlocking is never automatic, and a masternode collateral is unlocked + /// only here. Returns `true` when the outpoint was locked. When the wallet + /// holds the coin, its value moves back to the spendable balance. + pub fn unlock_outpoint(&mut self, outpoint: &OutPoint) -> bool { + if !self.locked_outpoints.remove(outpoint) { + return false; + } + if self.refresh_lock_flags([*outpoint]) { + self.update_balance(); + } + true + } + + /// Lock the collateral `tx` registers when it is a ProRegTx. + /// + /// Returns the collateral when it was not locked before. Only updates the + /// set: the caller refreshes the flags of the coins involved. + pub(crate) fn lock_masternode_collateral(&mut self, tx: &Transaction) -> Option { + let collateral = masternode_collateral(tx)?; + self.locked_outpoints.insert(collateral).then_some(collateral) + } + + /// Set the lock flag of each coin this wallet holds among `outpoints` to + /// its membership in the lock set. Returns whether any flag changed, which + /// means the balance buckets are stale. + pub(crate) fn refresh_lock_flags( + &mut self, + outpoints: impl IntoIterator, + ) -> bool { + let locked = &self.locked_outpoints; + let mut accounts = self.accounts.all_funding_accounts_mut(); + let mut changed = false; + for outpoint in outpoints { + let is_locked = locked.contains(&outpoint); + for account in accounts.iter_mut() { + if let Some(utxo) = account.utxos.get_mut(&outpoint) { + changed |= utxo.is_locked != is_locked; + utxo.is_locked = is_locked; + } + } + } + changed + } + + /// Set the lock flag of every coin this wallet holds to its membership in + /// the lock set. + /// + /// Run before every balance refresh, so coins inserted without going + /// through transaction checking (a store restoring its coins, say) pick up + /// their locks too. + pub(crate) fn refresh_all_lock_flags(&mut self) { + let locked = &self.locked_outpoints; + for account in self.accounts.all_funding_accounts_mut() { + for utxo in account.utxos.values_mut() { + utxo.is_locked = locked.contains(&utxo.outpoint); + } + } + } +} + +#[cfg(test)] +mod tests { + use super::masternode_collateral; + use dashcore::blockdata::transaction::special_transaction::provider_registration::{ + ProviderMasternodeType, ProviderRegistrationPayload, + }; + use dashcore::blockdata::transaction::special_transaction::TransactionPayload; + use dashcore::bls_sig_utils::BLSPublicKey; + use dashcore::hash_types::InputsHash; + use dashcore::hashes::Hash; + use dashcore::{Address, Network, OutPoint, PubkeyHash, ScriptBuf, Transaction, TxOut, Txid}; + + /// A ProRegTx naming `collateral`, with `outputs` outputs of its own. + fn registration(collateral: OutPoint, outputs: usize) -> Transaction { + let key_hash = PubkeyHash::from_byte_array([0x70; 20]); + Transaction { + version: 3, + lock_time: 0, + input: Vec::new(), + output: vec![ + TxOut { + value: 1_000, + script_pubkey: Address::dummy(Network::Testnet, 1).script_pubkey(), + }; + outputs + ], + special_transaction_payload: Some(TransactionPayload::ProviderRegistrationPayloadType( + ProviderRegistrationPayload { + version: 1, + masternode_type: ProviderMasternodeType::Regular, + masternode_mode: 0, + collateral_outpoint: collateral, + service_address: "127.0.0.1:19999".parse().expect("socket address"), + owner_key_hash: key_hash, + operator_public_key: BLSPublicKey::from([0x11; 48]), + voting_key_hash: key_hash, + operator_reward: 0, + script_payout: ScriptBuf::new(), + inputs_hash: InputsHash::all_zeros(), + signature: vec![0x33; 65], + platform_node_id: None, + platform_p2p_port: None, + platform_http_port: None, + }, + )), + } + } + + #[test] + fn an_external_collateral_is_the_outpoint_the_registration_names() { + let named = OutPoint::new(Txid::from_byte_array([0x19; 32]), 3); + assert_eq!(masternode_collateral(®istration(named, 1)), Some(named)); + } + + #[test] + fn a_null_collateral_txid_names_the_registrations_own_output() { + let tx = registration(OutPoint::new(Txid::all_zeros(), 1), 2); + assert_eq!(masternode_collateral(&tx), Some(OutPoint::new(tx.txid(), 1))); + } + + #[test] + fn an_own_output_index_past_the_outputs_names_no_coin() { + let tx = registration(OutPoint::new(Txid::all_zeros(), 2), 2); + assert_eq!(masternode_collateral(&tx), None); + } + + #[test] + fn only_a_registration_has_a_collateral() { + let address = Address::dummy(Network::Testnet, 1); + assert_eq!(masternode_collateral(&Transaction::dummy(&address, 0..1, &[1_000])), None); + } +} diff --git a/key-wallet/src/wallet/managed_wallet_info/mod.rs b/key-wallet/src/wallet/managed_wallet_info/mod.rs index 0d288e35f..48ada2126 100644 --- a/key-wallet/src/wallet/managed_wallet_info/mod.rs +++ b/key-wallet/src/wallet/managed_wallet_info/mod.rs @@ -8,6 +8,7 @@ pub mod coin_selection; pub mod fee; pub mod helpers; pub use helpers::AbandonOutcome; +mod locked_outpoints; pub mod managed_account_operations; pub mod managed_accounts; pub mod transaction_builder; @@ -28,7 +29,7 @@ use dashcore::prelude::CoreBlockHeight; use dashcore::{Address, Transaction, Txid}; #[cfg(feature = "serde")] use serde::{Deserialize, Serialize}; -use std::collections::{BTreeMap, HashSet}; +use std::collections::{BTreeMap, BTreeSet, HashSet}; /// Information about a managed wallet /// @@ -141,6 +142,16 @@ pub struct ManagedWalletInfo { pub(crate) account_generation: u64, #[cfg_attr(feature = "serde", serde(skip))] pub(crate) noted_chain_lock_height: Option, + /// Outpoints the wallet will not spend: masternode collateral, and + /// anything locked by hand. The source of truth for coin locks; see + /// [`Self::locked_outpoints`] for the rules. + /// + /// `#[serde(default)]` loads a snapshot written before this field existed + /// with no locks, in self-describing formats (e.g. JSON). As with + /// `observed_spent_outpoints`, non-self-describing serde formats cannot + /// default a missing field. + #[cfg_attr(feature = "serde", serde(default))] + pub(crate) locked_outpoints: BTreeSet, } /// Serde adapter for [`ManagedWalletInfo::observed_spent_outpoints`] that @@ -247,6 +258,7 @@ impl ManagedWalletInfo { observed_spent_outpoints: BTreeMap::new(), account_generation: 0, noted_chain_lock_height: None, + locked_outpoints: BTreeSet::new(), } } @@ -264,6 +276,7 @@ impl ManagedWalletInfo { observed_spent_outpoints: BTreeMap::new(), account_generation: 0, noted_chain_lock_height: None, + locked_outpoints: BTreeSet::new(), } } @@ -291,6 +304,7 @@ impl ManagedWalletInfo { observed_spent_outpoints: BTreeMap::new(), account_generation: 0, noted_chain_lock_height: None, + locked_outpoints: BTreeSet::new(), } } diff --git a/key-wallet/src/wallet/managed_wallet_info/transaction_builder.rs b/key-wallet/src/wallet/managed_wallet_info/transaction_builder.rs index 0c3312339..b1deec7eb 100644 --- a/key-wallet/src/wallet/managed_wallet_info/transaction_builder.rs +++ b/key-wallet/src/wallet/managed_wallet_info/transaction_builder.rs @@ -144,7 +144,9 @@ impl TransactionBuilder { } /// Add a funding account's spendable UTXOs to the candidate input set, - /// skipping any already reserved by another in-flight build. + /// skipping any already reserved by another in-flight build and any the + /// wallet has locked (see + /// [`ManagedWalletInfo::locked_outpoints`](crate::wallet::ManagedWalletInfo::locked_outpoints)). /// /// Call it once per funding account: coin selection then draws from the /// union of their UTXOs, and the first account supplies the change @@ -179,8 +181,9 @@ impl TransactionBuilder { /// does. /// /// Reservation bookkeeping is unchanged: `owned` still covers every - /// unreserved UTXO of the account, so whichever seeded outpoints selection - /// picks are reserved by the account that holds them. + /// unreserved, unlocked UTXO of the account, so whichever seeded outpoints + /// selection picks are reserved by the account that holds them. A seeded + /// outpoint the account holds locked is dropped, as with `add_funding`. pub fn add_funding_reservation_only( self, funds_acc: &mut ManagedCoreFundsAccount, @@ -212,10 +215,19 @@ impl TransactionBuilder { // here would leave a pre-seeded input unreserved and free for a // concurrent build to select. let mut owned: HashSet = HashSet::new(); + // Coins the wallet has locked, such as masternode collateral. Never a + // candidate, and a copy seeded by `add_inputs` is dropped below: a + // caller-built `Utxo` carries whatever lock flag it was cloned with, + // while this account's own coin carries the current one. + let mut locked: HashSet = HashSet::new(); for utxo in funds_acc.utxos.values() { if reserved.contains(&utxo.outpoint) { continue; } + if utxo.is_locked { + locked.insert(utxo.outpoint); + continue; + } owned.insert(utxo.outpoint); if present.contains(&utxo.outpoint) { continue; @@ -225,6 +237,9 @@ impl TransactionBuilder { } } self.funding.push((funds_acc.reservations().clone(), owned)); + if !locked.is_empty() { + self.inputs.retain(|utxo| !locked.contains(&utxo.outpoint)); + } self.inputs.extend(candidates); if self.change_addr.is_none() { self.change_addr = funds_acc.next_change_address(Some(&acc.account_xpub), true).ok(); 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 1dabac23d..74df03808 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 @@ -118,7 +118,8 @@ pub trait WalletInfoInterface: Sized + WalletTransactionChecker + ManagedAccount /// Get all UTXOs for the wallet fn utxos(&self) -> BTreeSet<&Utxo>; - /// Get spendable UTXOs (confirmed and not locked) + /// Get spendable UTXOs: mature and not locked (see + /// [`ManagedWalletInfo::locked_outpoints`]). fn get_spendable_utxos(&self) -> BTreeSet<&Utxo>; /// Get the wallet balance @@ -483,6 +484,10 @@ impl WalletInfoInterface for ManagedWalletInfo { } fn update_balance(&mut self) { + // The locked bucket is read from each coin's lock flag, which follows + // the wallet's lock set; bring every flag up to date first. + self.refresh_all_lock_flags(); + // Only funds-bearing accounts contribute to the wallet balance. let mut balance = WalletCoreBalance::default(); let last_processed_height = self.last_processed_height(); From 16c1795f1049a163b01dfe7fea90fde6e7a7be8a Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Tue, 29 Sep 2026 01:50:42 +0700 Subject: [PATCH 2/3] fix(key-wallet): lock external collateral only from a block External collateral is locked only once its ProRegTx is in a block (InBlock or InChainLockedBlock). Until then the ProRegTx is not a registration: the network may never accept it, and the wallet does not check its payload itself. An InstantSend context counts as unconfirmed, since the wallet does not verify InstantSend locks and cannot tell whether its caller did. A ProRegTx first seen in the mempool locks the collateral it names at the block that confirms it, and the collateral may still arrive before or after that block. Dash Core likewise locks such a collateral once a block adds the registration to its masternode list. A collateral the ProRegTx creates itself (a null collateral txid) is still locked from any sighting, mempool included, as the coin arrives: it is the ProRegTx's own output. An unconfirmed sighting does not lock that output again once the wallet holds it; a block does. A lock refreshes the balance. `CheckTransactionsResult` lists each wallet's new locks in `per_wallet_locked_outpoints`, relevant or not, and the mempool path refreshes those wallets' balances as well as the affected ones. Off-chain, a lock can only land on a coin arriving with the ProRegTx, so `TransactionDetected` carries it in the locked balance; in a block, `BlockProcessed` carries it. Co-Authored-By: Claude Opus 5.5 --- key-wallet-manager/src/event_tests.rs | 192 +++++++++++++++++- key-wallet-manager/src/lib.rs | 17 ++ key-wallet-manager/src/process_block.rs | 14 +- .../src/tests/locked_outpoints_tests.rs | 106 ++++++++++ .../transaction_checking/account_checker.rs | 10 +- .../transaction_checking/wallet_checker.rs | 11 +- .../managed_wallet_info/locked_outpoints.rs | 69 ++++++- 7 files changed, 394 insertions(+), 25 deletions(-) diff --git a/key-wallet-manager/src/event_tests.rs b/key-wallet-manager/src/event_tests.rs index afccc35ae..25f0278fa 100644 --- a/key-wallet-manager/src/event_tests.rs +++ b/key-wallet-manager/src/event_tests.rs @@ -4,25 +4,28 @@ use crate::wallet_interface::WalletInterface; use dashcore::block::{Block, Header, Version}; use dashcore::blockdata::script::Builder; use dashcore::blockdata::transaction::special_transaction::asset_lock::AssetLockPayload; +use dashcore::blockdata::transaction::special_transaction::provider_registration::{ + ProviderMasternodeType, ProviderRegistrationPayload, +}; use dashcore::blockdata::transaction::special_transaction::TransactionPayload; -use dashcore::bls_sig_utils::BLSSignature; +use dashcore::bls_sig_utils::{BLSPublicKey, BLSSignature}; use dashcore::ephemerealdata::chain_lock::ChainLock; use dashcore::ephemerealdata::instant_lock::InstantLock; -use dashcore::hash_types::CycleHash; +use dashcore::hash_types::{CycleHash, InputsHash}; use dashcore::hashes::Hash; use dashcore::opcodes; use dashcore::{ - BlockHash, CompactTarget, OutPoint, PublicKey, ScriptBuf, TxIn, TxMerkleNode, TxOut, Txid, - Witness, + BlockHash, CompactTarget, OutPoint, PubkeyHash, PublicKey, ScriptBuf, TxIn, TxMerkleNode, + TxOut, Txid, Witness, }; use key_wallet::account::StandardAccountType; use key_wallet::managed_account::address_pool::{AddressPoolType, PublicKeyType}; use key_wallet::managed_account::managed_account_trait::ManagedAccountTrait; use key_wallet::managed_account::managed_account_type::ManagedAccountType; -use key_wallet::transaction_checking::{TransactionRouter, TransactionType}; +use key_wallet::transaction_checking::{BlockInfo, TransactionRouter, TransactionType}; use key_wallet::wallet::managed_wallet_info::transaction_building::AccountTypePreference; use key_wallet::AccountType; -use std::collections::BTreeSet; +use std::collections::{BTreeMap, BTreeSet}; fn make_block(txdata: Vec, seed: u8, time: u32) -> Block { Block { @@ -1270,6 +1273,183 @@ async fn test_update_wallet_synced_height_does_not_re_emit_when_unchanged() { ); } +// --------------------------------------------------------------------------- +// Masternode collateral locks +// --------------------------------------------------------------------------- + +/// A ProRegTx registering `collateral` and paying `outputs`. Its fee input and +/// keys belong to no one the test wallet knows; `seed` varies the txid. +fn masternode_registration(collateral: OutPoint, outputs: Vec, seed: u8) -> Transaction { + let key_hash = PubkeyHash::from_byte_array([0x70; 20]); + Transaction { + version: 3, + lock_time: 0, + input: vec![TxIn { + previous_output: OutPoint::new(Txid::from_byte_array([seed; 32]), 0), + ..Default::default() + }], + output: outputs, + special_transaction_payload: Some(TransactionPayload::ProviderRegistrationPayloadType( + ProviderRegistrationPayload { + version: 1, + masternode_type: ProviderMasternodeType::Regular, + masternode_mode: 0, + collateral_outpoint: collateral, + service_address: "127.0.0.1:19999".parse().expect("socket address"), + owner_key_hash: key_hash, + operator_public_key: BLSPublicKey::from([0x11; 48]), + voting_key_hash: key_hash, + operator_reward: 0, + script_payout: ScriptBuf::new(), + inputs_hash: InputsHash::all_zeros(), + signature: vec![0x33; 65], + platform_node_id: None, + platform_p2p_port: None, + platform_http_port: None, + }, + )), + } +} + +fn bip44_account_0() -> AccountType { + AccountType::Standard { + index: 0, + standard_account_type: StandardAccountType::BIP44Account, + } +} + +/// A wallet holding one coin of `TX_AMOUNT`, mined at height 100. +async fn manager_holding_a_coin() -> (WalletManager, WalletId, OutPoint) { + let (mut manager, wallet_id, addr) = setup_manager_with_wallet(); + let funding = create_tx_paying_to(&addr, 0xc0); + let block = make_block(vec![funding.clone()], 0xc0, 1_000); + manager + .process_block_for_wallets(&block, block.block_hash(), 100, &BTreeSet::from([wallet_id])) + .await; + (manager, wallet_id, OutPoint::new(funding.txid(), 0)) +} + +/// A ProRegTx locks a collateral it names at the block that holds it, not +/// from the mempool. The mempool sighting changes nothing and emits nothing; +/// the block's `BlockProcessed` carries the coin in the locked balance. +#[tokio::test] +async fn test_registration_locks_a_named_collateral_at_its_block_not_from_the_mempool() { + let (mut manager, wallet_id, collateral) = manager_holding_a_coin().await; + let registration = masternode_registration(collateral, vec![], 0xc1); + let mut rx = manager.subscribe_events(); + + let result = manager.process_mempool_transaction(®istration, None).await; + + assert!(!result.is_relevant); + assert_no_events(&mut rx); + let info = manager.get_wallet_info(&wallet_id).expect("wallet info"); + assert!(!info.is_outpoint_locked(&collateral)); + assert_eq!(info.balance().spendable(), TX_AMOUNT); + assert_eq!(info.balance().locked(), 0); + + let block = make_block(vec![registration], 0xc1, 1_001); + manager + .process_block_for_wallets(&block, block.block_hash(), 101, &BTreeSet::from([wallet_id])) + .await; + + assert!(manager + .get_wallet_info(&wallet_id) + .expect("wallet info") + .is_outpoint_locked(&collateral)); + let events = drain_events(&mut rx); + assert_eq!(events.len(), 1, "one BlockProcessed expected, got {:?}", events); + match &events[0] { + WalletEvent::BlockProcessed { + inserted, + updated, + balance, + account_balances, + .. + } => { + assert!(inserted.is_empty() && updated.is_empty(), "the ProRegTx records nothing"); + assert_eq!(balance.locked(), TX_AMOUNT); + assert_eq!(balance.spendable(), 0); + let account = account_balances.get(&bip44_account_0()).expect("the coin's account"); + assert_eq!(account.locked(), TX_AMOUNT); + } + other => panic!("expected BlockProcessed, got {:?}", other), + } +} + +/// An InstantSend lock does not make a ProRegTx a registration: the coin it +/// names stays spendable until a block holds the ProRegTx. +#[tokio::test] +async fn test_instant_locked_registration_locks_no_collateral_it_names() { + let (mut manager, wallet_id, collateral) = manager_holding_a_coin().await; + let registration = masternode_registration(collateral, vec![], 0xc2); + let mut rx = manager.subscribe_events(); + + manager + .process_mempool_transaction(®istration, Some(dummy_instant_lock(registration.txid()))) + .await; + + assert_no_events(&mut rx); + let info = manager.get_wallet_info(&wallet_id).expect("wallet info"); + assert!(!info.is_outpoint_locked(&collateral)); + assert_eq!(info.balance().spendable(), TX_AMOUNT); + assert_eq!(info.balance().locked(), 0); +} + +/// A ProRegTx that creates its collateral locks it from the mempool, and the +/// `TransactionDetected` for the coin carries it in the locked balance. +#[tokio::test] +async fn test_mempool_registration_creating_its_collateral_emits_the_locked_balance() { + let (mut manager, wallet_id, addr) = setup_manager_with_wallet(); + let to_wallet = TxOut { + value: TX_AMOUNT, + script_pubkey: addr.script_pubkey(), + }; + // A null collateral txid: the collateral is this ProRegTx's output 0. + let registration = + masternode_registration(OutPoint::new(Txid::all_zeros(), 0), vec![to_wallet], 0xc3); + let collateral = OutPoint::new(registration.txid(), 0); + let mut rx = manager.subscribe_events(); + + let result = manager.process_mempool_transaction(®istration, None).await; + + assert!(result.is_relevant); + let events = drain_events(&mut rx); + assert_eq!(events.len(), 1, "one TransactionDetected expected, got {:?}", events); + match &events[0] { + WalletEvent::TransactionDetected { + record, + balance, + account_balances, + .. + } => { + assert_eq!(record.txid, registration.txid()); + assert_eq!(balance.locked(), TX_AMOUNT); + assert_eq!(balance.spendable(), 0, "the collateral is not spendable balance"); + let account = account_balances.get(&bip44_account_0()).expect("the coin's account"); + assert_eq!(account.locked(), TX_AMOUNT); + } + other => panic!("expected TransactionDetected, got {:?}", other), + } + let info = manager.get_wallet_info(&wallet_id).expect("wallet info"); + assert!(info.is_outpoint_locked(&collateral)); + assert_eq!(info.balance().locked(), TX_AMOUNT); +} + +/// A check reports the locks it took per wallet, including for a wallet the +/// transaction is otherwise irrelevant to, so a caller that checks with +/// `update_balance = false` knows which balances to refresh. +#[tokio::test] +async fn test_check_transaction_reports_a_lock_for_a_wallet_it_is_otherwise_irrelevant_to() { + let (mut manager, wallet_id, collateral) = manager_holding_a_coin().await; + let registration = masternode_registration(collateral, vec![], 0xc4); + let mined = TransactionContext::InBlock(BlockInfo::new(101, BlockHash::all_zeros(), 1_001)); + + let result = manager.check_transaction_in_all_wallets(®istration, mined, true, false).await; + + assert!(result.affected_wallets.is_empty()); + assert_eq!(result.per_wallet_locked_outpoints, BTreeMap::from([(wallet_id, vec![collateral])])); +} + // --------------------------------------------------------------------------- // Dry run and irrelevant paths // --------------------------------------------------------------------------- diff --git a/key-wallet-manager/src/lib.rs b/key-wallet-manager/src/lib.rs index 798f1ce17..4fe946d89 100644 --- a/key-wallet-manager/src/lib.rs +++ b/key-wallet-manager/src/lib.rs @@ -109,6 +109,15 @@ pub struct CheckTransactionsResult { /// see [`crate::events::WalletEvent::TransactionsSwept`] for why a /// consumer needs this set named explicitly instead of re-deriving it. pub per_wallet_released_outpoints: BTreeMap>, + /// Outpoints this check added to each wallet's lock set, grouped by + /// wallet: the collateral of a ProRegTx (see + /// [`ManagedWalletInfo::locked_outpoints`]). Gathered whether or not the + /// transaction is relevant to the wallet, since a ProRegTx in a block + /// locks a coin the wallet holds even when nothing else ties it to the + /// wallet. A lock moves that coin from the spendable to the locked + /// balance, so a caller that checked with `update_balance = false` + /// refreshes these wallets as well as the affected ones. + pub per_wallet_locked_outpoints: BTreeMap>, } impl CheckTransactionsResult { @@ -662,6 +671,14 @@ impl WalletManager { .extend(check_result.released_outpoints); } + if !check_result.locked_outpoints.is_empty() { + result + .per_wallet_locked_outpoints + .entry(*wallet_id) + .or_default() + .extend(check_result.locked_outpoints); + } + if !check_result.new_addresses.is_empty() { result .new_addresses diff --git a/key-wallet-manager/src/process_block.rs b/key-wallet-manager/src/process_block.rs index 5d9b61092..f371eb53f 100644 --- a/key-wallet-manager/src/process_block.rs +++ b/key-wallet-manager/src/process_block.rs @@ -175,11 +175,23 @@ impl WalletInterface for WalletM // changed. The cached `.balance` field is stale until // `update_balance()` runs, so the pre-snapshot taken here captures // the pre-transaction state. + // + // A wallet whose lock set this check grew is refreshed too, relevant + // or not, since a lock moves a held coin to the locked balance. + // Off-chain only a ProRegTx's own output locks, and only as that coin + // arrives, so the lock rides the `TransactionDetected` of the wallet + // the ProRegTx pays. + let refreshed: BTreeSet = check_result + .affected_wallets + .iter() + .chain(check_result.per_wallet_locked_outpoints.keys()) + .copied() + .collect(); let mut per_wallet_account_diff: BTreeMap< WalletId, BTreeMap, > = BTreeMap::new(); - for wallet_id in &check_result.affected_wallets { + for wallet_id in &refreshed { if let Some(info) = self.wallet_infos.get_mut(wallet_id) { let prior = info.account_balances(); info.update_balance(); diff --git a/key-wallet/src/tests/locked_outpoints_tests.rs b/key-wallet/src/tests/locked_outpoints_tests.rs index 4bd2d294c..53cca5cee 100644 --- a/key-wallet/src/tests/locked_outpoints_tests.rs +++ b/key-wallet/src/tests/locked_outpoints_tests.rs @@ -12,6 +12,7 @@ use dashcore::blockdata::transaction::special_transaction::provider_update_revoc use dashcore::blockdata::transaction::special_transaction::provider_update_service::ProviderUpdateServicePayload; use dashcore::blockdata::transaction::special_transaction::TransactionPayload; use dashcore::bls_sig_utils::{BLSPublicKey, BLSSignature}; +use dashcore::ephemerealdata::instant_lock::InstantLock; use dashcore::hash_types::InputsHash; use dashcore::hashes::Hash; use dashcore::{ @@ -44,6 +45,27 @@ fn block(height: u32) -> TransactionContext { )) } +fn chain_locked_block(height: u32) -> TransactionContext { + TransactionContext::InChainLockedBlock(BlockInfo::new( + height, + BlockHash::from_byte_array([height as u8; 32]), + 1_700_000_000 + height, + )) +} + +/// Seen in the mempool, without an InstantSend lock. +fn in_mempool(_tx: &Transaction) -> TransactionContext { + TransactionContext::Mempool +} + +/// Seen in the mempool with an InstantSend lock. +fn instant_locked(tx: &Transaction) -> TransactionContext { + TransactionContext::InstantSend(InstantLock { + txid: tx.txid(), + ..InstantLock::default() + }) +} + /// An address that is not the wallet's. fn elsewhere() -> Address { Address::from_str("yTb47qEBpNmgXvYYsHEN4nh8yJwa5iC4Cs").expect("testnet address") @@ -226,6 +248,8 @@ async fn a_registration_locks_its_external_collateral_whichever_arrives_first( } #[test_case(&[TransactionContext::Mempool, block(101)] ; "seen in the mempool, then mined")] +#[test_case(&[TransactionContext::Mempool] ; "seen only in the mempool")] +#[test_case(&[TransactionContext::InstantSend(InstantLock::default())] ; "seen instant send locked")] #[test_case(&[block(101)] ; "first seen mined")] #[tokio::test] async fn a_registration_locks_the_collateral_it_creates(sightings: &[TransactionContext]) { @@ -260,6 +284,88 @@ async fn a_registration_locks_the_collateral_it_creates(sightings: &[Transaction assert!(is_out_of_coins(send(&mut ctx, DASH, SelectionStrategy::LargestFirst))); } +/// A ProRegTx that is not in a block is not a registration yet, so the coin +/// it names stays spendable. An InstantSend lock does not change that. +#[test_case(in_mempool ; "in the mempool")] +#[test_case(instant_locked ; "instant send locked")] +#[tokio::test] +async fn an_unconfirmed_registration_leaves_the_collateral_it_names_unlocked( + sighting: fn(&Transaction) -> TransactionContext, +) { + let mut ctx = TestWalletContext::new_random(); + let collateral = receive(&mut ctx, COLLATERAL, 0x01, 100).await; + ctx.managed_wallet.update_last_processed_height(TIP); + let registration = registration(collateral, vec![], 0xEE); + + let result = ctx.check_transaction(®istration, sighting(®istration)).await; + + assert!(result.locked_outpoints.is_empty()); + assert!(!result.state_modified, "nothing changed"); + assert!(!ctx.managed_wallet.is_outpoint_locked(&collateral)); + assert!(!ctx.bip44_account().utxos[&collateral].is_locked); + assert_eq!(ctx.managed_wallet.balance().spendable(), COLLATERAL); + assert_eq!(ctx.managed_wallet.balance().locked(), 0); + let tx = send(&mut ctx, DASH, SelectionStrategy::LargestFirst).expect("the coin is spendable"); + assert_eq!(spent(&tx), vec![collateral]); +} + +/// The block that confirms a ProRegTx first seen unconfirmed locks the +/// collateral it names. +#[test_case(in_mempool, block(101) ; "mempool, then a block")] +#[test_case(in_mempool, chain_locked_block(101) ; "mempool, then a chainlocked block")] +#[test_case(instant_locked, block(101) ; "instant send, then a block")] +#[tokio::test] +async fn the_block_holding_a_registration_first_seen_unconfirmed_locks_its_collateral( + first: fn(&Transaction) -> TransactionContext, + mined: TransactionContext, +) { + let mut ctx = TestWalletContext::new_random(); + let collateral = receive(&mut ctx, COLLATERAL, 0x01, 100).await; + let registration = registration(collateral, vec![], 0xEE); + let unconfirmed = ctx.check_transaction(®istration, first(®istration)).await; + assert!(unconfirmed.locked_outpoints.is_empty()); + + let result = ctx.check_transaction(®istration, mined).await; + + assert_eq!(result.locked_outpoints, vec![collateral]); + assert!(result.state_modified, "the lock set is persisted state"); + assert!(ctx.bip44_account().utxos[&collateral].is_locked); + assert_eq!(ctx.managed_wallet.balance().locked(), COLLATERAL); + ctx.managed_wallet.update_last_processed_height(TIP); + assert!(is_out_of_coins(send(&mut ctx, DASH, SelectionStrategy::LargestFirst))); +} + +/// An unconfirmed sighting locks the collateral a ProRegTx creates as that +/// coin arrives, not again once the wallet holds it: an unlock stays until a +/// block holding the ProRegTx locks the coin again. +#[test_case(in_mempool ; "in the mempool")] +#[test_case(instant_locked ; "instant send locked")] +#[tokio::test] +async fn an_unconfirmed_sighting_does_not_relock_a_created_collateral_after_an_unlock( + sighting: fn(&Transaction) -> TransactionContext, +) { + let mut ctx = TestWalletContext::new_random(); + let to_wallet = TxOut { + value: COLLATERAL, + script_pubkey: ctx.receive_address.script_pubkey(), + }; + let registration = registration(OutPoint::new(Txid::all_zeros(), 0), vec![to_wallet], 0xEE); + let collateral = OutPoint::new(registration.txid(), 0); + let first = ctx.check_transaction(®istration, TransactionContext::Mempool).await; + assert_eq!(first.locked_outpoints, vec![collateral]); + assert!(ctx.managed_wallet.unlock_outpoint(&collateral)); + + let again = ctx.check_transaction(®istration, sighting(®istration)).await; + + assert!(again.locked_outpoints.is_empty()); + assert!(!ctx.managed_wallet.is_outpoint_locked(&collateral)); + assert_eq!(ctx.managed_wallet.balance().locked(), 0); + + let mined = ctx.check_transaction(®istration, block(101)).await; + assert_eq!(mined.locked_outpoints, vec![collateral]); + assert_eq!(ctx.managed_wallet.balance().locked(), COLLATERAL); +} + #[tokio::test] async fn unlocking_lets_a_send_spend_the_collateral_and_relocking_stops_it_again() { let (mut ctx, collateral, _) = registered_wallet(None).await; diff --git a/key-wallet/src/transaction_checking/account_checker.rs b/key-wallet/src/transaction_checking/account_checker.rs index e3a23bd51..07bfefb55 100644 --- a/key-wallet/src/transaction_checking/account_checker.rs +++ b/key-wallet/src/transaction_checking/account_checker.rs @@ -103,13 +103,17 @@ pub struct TransactionCheckResult { pub released_outpoints: Vec, /// Outpoints this check added to the wallet's lock set: the collateral of /// a ProRegTx, which coin selection now skips. Only new entries are - /// listed, so a ProRegTx seen again reports nothing. + /// listed, so a ProRegTx seen again reports nothing. A collateral the + /// ProRegTx names is locked only in a block context; see + /// [`ManagedWalletInfo::locked_outpoints`](crate::wallet::ManagedWalletInfo::locked_outpoints). /// /// Filled whether or not the transaction is otherwise relevant: the /// registration may involve nothing of this wallet's but the collateral, /// or the collateral may not have arrived yet. A store that persists - /// wallet state records these; see - /// [`ManagedWalletInfo::locked_outpoints`](crate::wallet::ManagedWalletInfo::locked_outpoints). + /// wallet state records these. A lock moves a coin the wallet holds from + /// the spendable to the locked balance, so a caller that checked with + /// `update_balance = false` refreshes the balance of a wallet whose check + /// lists any, as it does for a relevant transaction. pub locked_outpoints: Vec, } diff --git a/key-wallet/src/transaction_checking/wallet_checker.rs b/key-wallet/src/transaction_checking/wallet_checker.rs index 3e2b9af5c..85fe852ce 100644 --- a/key-wallet/src/transaction_checking/wallet_checker.rs +++ b/key-wallet/src/transaction_checking/wallet_checker.rs @@ -32,9 +32,12 @@ pub trait WalletTransactionChecker { /// The context parameter indicates where the transaction comes from (mempool, block, etc.) /// /// With `update_state`, a ProRegTx also locks the collateral it - /// registers, relevant or not, so coin selection skips it; new locks are - /// listed in [`TransactionCheckResult::locked_outpoints`]. See - /// [`ManagedWalletInfo::locked_outpoints`]. + /// registers, relevant or not, so coin selection skips it: a collateral it + /// names once the ProRegTx is in a block, its own output from any context. + /// New locks are listed in [`TransactionCheckResult::locked_outpoints`]; + /// with `update_balance = false`, refresh the balance of a wallet whose + /// check lists any, since a lock moves a held coin to the locked balance. + /// See [`ManagedWalletInfo::locked_outpoints`]. async fn check_core_transaction( &mut self, tx: &Transaction, @@ -125,7 +128,7 @@ impl WalletTransactionChecker for ManagedWalletInfo { // Before the accounts record `tx`, so a collateral the ProRegTx // creates itself is locked from the moment it becomes a coin. - let collateral = self.lock_masternode_collateral(tx); + let collateral = self.lock_masternode_collateral(tx, &context); let mut result = self .check_core_transaction_inner(tx, context, wallet, update_state, update_balance) diff --git a/key-wallet/src/wallet/managed_wallet_info/locked_outpoints.rs b/key-wallet/src/wallet/managed_wallet_info/locked_outpoints.rs index 8a5da617b..9f5eda217 100644 --- a/key-wallet/src/wallet/managed_wallet_info/locked_outpoints.rs +++ b/key-wallet/src/wallet/managed_wallet_info/locked_outpoints.rs @@ -7,6 +7,7 @@ //! [`ManagedWalletInfo::locked_outpoints`] for the full rules. use super::ManagedWalletInfo; +use crate::transaction_checking::TransactionContext; use crate::wallet::managed_wallet_info::wallet_info_interface::WalletInfoInterface; use dashcore::blockdata::transaction::special_transaction::TransactionPayload; use dashcore::hashes::Hash; @@ -42,11 +43,26 @@ impl ManagedWalletInfo { /// /// # What locks an outpoint /// - /// - A ProRegTx. The wallet locks the collateral of every masternode - /// registration it processes, so an ordinary send never spends it: + /// - A ProRegTx. The wallet locks the collateral of the masternode + /// registrations it processes, so an ordinary send never spends it: /// spending the collateral would end the registration. The collateral is /// the ProRegTx's `collateralOutpoint`, or, when that names a null txid, - /// the ProRegTx's own output at `collateralIndex`. + /// the ProRegTx's own output at `collateralIndex`. When it is locked + /// depends on which: + /// - A collateral the ProRegTx names is locked once the ProRegTx is in a + /// block ([`TransactionContext::InBlock`] or + /// [`TransactionContext::InChainLockedBlock`]). Until then it is not a + /// registration: the network may never accept it, and the wallet does + /// not check a ProRegTx's payload itself. Dash Core likewise locks such + /// a collateral once a block adds the registration to its masternode + /// list. An [`TransactionContext::InstantSend`] context counts as + /// unconfirmed here: the wallet does not verify InstantSend locks, and + /// cannot tell whether its caller did. + /// - A collateral the ProRegTx creates is locked from its first + /// sighting, mempool included, as the coin arrives: it is the + /// ProRegTx's own output, so the lock can hold no other coin. An + /// unconfirmed sighting does not lock that output again once the + /// wallet holds it; a block does. /// - [`Self::lock_outpoint`]. /// /// Only [`Self::unlock_outpoint`] removes an outpoint. A coin's amount is @@ -54,10 +70,10 @@ impl ManagedWalletInfo { /// /// # Order does not matter /// - /// An entry does not need a coin behind it. A collateral seen after its - /// ProRegTx, or a coin locked before it arrives, arrives locked. A ProRegTx - /// naming a coin that is not this wallet's leaves an entry that never - /// matches anything. + /// An entry does not need a coin behind it. A collateral seen after the + /// block holding its ProRegTx, or a coin locked before it arrives, arrives + /// locked. A ProRegTx naming a coin that is not this wallet's leaves an + /// entry that never matches anything. /// /// # How long a lock lasts /// @@ -72,8 +88,9 @@ impl ManagedWalletInfo { /// coin is spent the entry has nothing to act on, and a coin whose spend is /// reorged out or swept comes back locked. /// - /// Processing a ProRegTx again (the block that confirms it, a rescan) locks - /// its collateral again, as Core does on load. + /// Processing a ProRegTx in a block again (a rescan, or the block that + /// confirms a ProRegTx first seen in the mempool) locks its collateral + /// again, as Core does on load. /// /// # The set is the source of truth /// @@ -84,6 +101,13 @@ impl ManagedWalletInfo { /// unlocked, and on every balance refresh. A flag written on a held coin /// directly is overwritten by the next refresh. /// + /// A lock or an unlock moves a held coin between the spendable and the + /// locked balance. [`Self::lock_outpoint`], [`Self::unlock_outpoint`] and a + /// transaction check with `update_balance` refresh the balance themselves; + /// a check without it leaves the refresh to its caller, which refreshes + /// every wallet whose check lists a lock in + /// [`TransactionCheckResult::locked_outpoints`](crate::transaction_checking::TransactionCheckResult::locked_outpoints). + /// /// # Persistence /// /// The set is serialized with the wallet. A store that keeps wallet state @@ -134,15 +158,38 @@ impl ManagedWalletInfo { true } - /// Lock the collateral `tx` registers when it is a ProRegTx. + /// Lock the collateral `tx` registers when it is a ProRegTx that locks it + /// in `context`: a collateral it names only in a block, its own output in + /// a block or, unconfirmed, as that coin arrives. See + /// [`Self::locked_outpoints`]. /// /// Returns the collateral when it was not locked before. Only updates the /// set: the caller refreshes the flags of the coins involved. - pub(crate) fn lock_masternode_collateral(&mut self, tx: &Transaction) -> Option { + pub(crate) fn lock_masternode_collateral( + &mut self, + tx: &Transaction, + context: &TransactionContext, + ) -> Option { let collateral = masternode_collateral(tx)?; + if !context.confirmed() { + // Only a null collateral txid yields the ProRegTx's own txid: no + // transaction can name itself. + let creates_it = collateral.txid == tx.txid(); + if !creates_it || self.holds_coin(&collateral) { + return None; + } + } self.locked_outpoints.insert(collateral).then_some(collateral) } + /// Whether a funds account of this wallet holds `outpoint` as a coin. + fn holds_coin(&self, outpoint: &OutPoint) -> bool { + self.accounts + .all_funding_accounts() + .iter() + .any(|account| account.utxos.contains_key(outpoint)) + } + /// Set the lock flag of each coin this wallet holds among `outpoints` to /// its membership in the lock set. Returns whether any flag changed, which /// means the balance buckets are stale. From 44a9a010500fbd44aba09111b4c53a28b88e8073 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Tue, 29 Sep 2026 03:46:10 +0700 Subject: [PATCH 3/3] fix(key-wallet): drop a locked input seeded after funding `add_funding` dropped the account's locked coins only from the inputs the builder held at that moment, so a stale copy of a locked coin (one cloned with `is_locked == false`) passed to `add_inputs` after the funding call reached coin selection and could be spent, masternode collateral included. Funding now records the outpoints the account holds locked on the builder, and `assemble_unsigned` drops them from the candidates just before coin selection, next to the reservation recheck. As with a reserved outpoint, a locked one is dropped silently rather than refused, whichever call came first. Inputs the accounts hold unlocked are kept as before. Co-Authored-By: Claude Opus 5.5 --- .../src/tests/locked_outpoints_tests.rs | 49 ++++++++++++++++--- .../transaction_builder.rs | 45 +++++++++++------ 2 files changed, 70 insertions(+), 24 deletions(-) diff --git a/key-wallet/src/tests/locked_outpoints_tests.rs b/key-wallet/src/tests/locked_outpoints_tests.rs index 53cca5cee..f71d9c17f 100644 --- a/key-wallet/src/tests/locked_outpoints_tests.rs +++ b/key-wallet/src/tests/locked_outpoints_tests.rs @@ -615,22 +615,55 @@ async fn special_transaction_funding_skips_the_collateral_even_when_seeded() { assert_eq!(spent(&tx), vec![spare.expect("spare coin")]); } +/// Funding records the coins the account holds locked, and the build drops +/// them just before coin selection, so a copy seeded after the funding call is +/// dropped too. `LargestFirst` would take the 1,000 DASH collateral first. +#[test_case(false ; "seeded before funding")] +#[test_case(true ; "seeded after funding")] +#[tokio::test] +async fn funding_drops_a_seeded_collateral(seeded_after_funding: bool) { + let (mut ctx, collateral, spare) = registered_wallet(Some(SPARE)).await; + let stale = stale_copy(&ctx, collateral); + let account = ctx.wallet.accounts.standard_bip44_accounts.get(&0).expect("BIP44").clone(); + let funds = ctx.managed_wallet.accounts.standard_bip44_accounts.get_mut(&0).expect("BIP44"); + + let builder = TransactionBuilder::new() + .set_current_height(TIP) + .set_selection_strategy(SelectionStrategy::LargestFirst); + let builder = if seeded_after_funding { + builder.add_funding(funds, &account).add_inputs([stale]) + } else { + builder.add_inputs([stale]).add_funding(funds, &account) + }; + let (tx, _fee, _reservation) = builder + .add_output(&elsewhere().assume_checked(), DASH) + .build_unsigned_reserved() + .expect("the spare coin funds the payment"); + + assert_eq!(spent(&tx), vec![spare.expect("spare coin")]); +} + /// The chunked drain path offers only what the caller seeds; a seeded copy of -/// a coin the account holds locked is dropped all the same. +/// a coin the account holds locked is dropped all the same, whichever call +/// comes first. +#[test_case(false ; "seeded before funding")] +#[test_case(true ; "seeded after funding")] #[tokio::test] -async fn reservation_only_funding_drops_a_seeded_collateral() { +async fn reservation_only_funding_drops_a_seeded_collateral(seeded_after_funding: bool) { let (mut ctx, collateral, _) = registered_wallet(None).await; let stale = stale_copy(&ctx, collateral); let account = ctx.wallet.accounts.standard_bip44_accounts.get(&0).expect("BIP44").clone(); let funds = ctx.managed_wallet.accounts.standard_bip44_accounts.get_mut(&0).expect("BIP44"); - let result = TransactionBuilder::new() + let builder = TransactionBuilder::new() .set_current_height(TIP) - .set_selection_strategy(SelectionStrategy::All) - .add_inputs([stale]) - .add_funding_reservation_only(funds, &account) - .add_output(&elsewhere().assume_checked(), DASH) - .build_unsigned_reserved(); + .set_selection_strategy(SelectionStrategy::All); + let builder = if seeded_after_funding { + builder.add_funding_reservation_only(funds, &account).add_inputs([stale]) + } else { + builder.add_inputs([stale]).add_funding_reservation_only(funds, &account) + }; + let result = builder.add_output(&elsewhere().assume_checked(), DASH).build_unsigned_reserved(); assert!(matches!(result, Err(BuilderError::CoinSelection(SelectionError::NoUtxosAvailable)))); } diff --git a/key-wallet/src/wallet/managed_wallet_info/transaction_builder.rs b/key-wallet/src/wallet/managed_wallet_info/transaction_builder.rs index b1deec7eb..42bd13c36 100644 --- a/key-wallet/src/wallet/managed_wallet_info/transaction_builder.rs +++ b/key-wallet/src/wallet/managed_wallet_info/transaction_builder.rs @@ -95,6 +95,11 @@ pub struct TransactionBuilder { /// account that holds the UTXO, so each account reserves its own share of /// the chosen inputs — all under the one token this build is stamped with. funding: Vec<(ReservationSet, HashSet)>, + /// Outpoints a funding account holds locked, such as masternode + /// collateral, captured by `add_funding`. Coin selection never sees them, + /// whether the account offered them or `add_inputs` seeded them, before + /// the funding call or after it: see `assemble_unsigned`. + locked: HashSet, } impl Default for TransactionBuilder { @@ -119,6 +124,7 @@ impl TransactionBuilder { special_payload: None, payload_finalizer: None, funding: Vec::new(), + locked: HashSet::new(), } } @@ -215,17 +221,17 @@ impl TransactionBuilder { // here would leave a pre-seeded input unreserved and free for a // concurrent build to select. let mut owned: HashSet = HashSet::new(); - // Coins the wallet has locked, such as masternode collateral. Never a - // candidate, and a copy seeded by `add_inputs` is dropped below: a - // caller-built `Utxo` carries whatever lock flag it was cloned with, - // while this account's own coin carries the current one. - let mut locked: HashSet = HashSet::new(); for utxo in funds_acc.utxos.values() { - if reserved.contains(&utxo.outpoint) { + // A coin the wallet has locked, such as masternode collateral, is + // never a candidate. Record it so `assemble_unsigned` also drops a + // copy seeded by `add_inputs`, before this call or after it: a + // caller-built `Utxo` carries whatever lock flag it was cloned + // with, while this account's own coin carries the current one. + if utxo.is_locked { + self.locked.insert(utxo.outpoint); continue; } - if utxo.is_locked { - locked.insert(utxo.outpoint); + if reserved.contains(&utxo.outpoint) { continue; } owned.insert(utxo.outpoint); @@ -237,9 +243,6 @@ impl TransactionBuilder { } } self.funding.push((funds_acc.reservations().clone(), owned)); - if !locked.is_empty() { - self.inputs.retain(|utxo| !locked.contains(&utxo.outpoint)); - } self.inputs.extend(candidates); if self.change_addr.is_none() { self.change_addr = funds_acc.next_change_address(Some(&acc.account_xpub), true).ok(); @@ -252,6 +255,11 @@ impl TransactionBuilder { self } + /// Add `inputs` to the candidate input set. + /// + /// In a funded build, an input that a funding account holds reserved or + /// locked is dropped just before coin selection, whether it was added + /// before the funding call or after it. pub fn add_inputs(mut self, inputs: impl IntoIterator) -> Self { self.inputs.extend(inputs); self @@ -578,18 +586,23 @@ impl TransactionBuilder { } if !self.funding.is_empty() { - // Every UTXO a funding account offers is unreserved, but a seeded - // one need not be: `add_inputs` does not consult a reservation set, - // and may run after the funding call. Drop those here so no path + // Every UTXO a funding account offers is unreserved and unlocked, + // but a seeded one need not be: `add_inputs` consults neither the + // reservation sets nor the accounts' locks, and may run after the + // funding call. Drop those here, just before selection, so no path // into the builder can spend an outpoint another in-flight build - // holds. + // holds or one the wallet has locked, such as masternode + // collateral. let height = self.current_height; let reserved: HashSet = self .funding .iter() .flat_map(|(reservations, _)| reservations.reserved(height)) .collect(); - self.inputs.retain(|utxo| !reserved.contains(&utxo.outpoint)); + let locked = &self.locked; + self.inputs.retain(|utxo| { + !reserved.contains(&utxo.outpoint) && !locked.contains(&utxo.outpoint) + }); } // Must match `calculate_base_size`, including the conservative VIN0 routing-script size.