/Users/eugenesiegel/btc/bitcoin/src/wallet/spend.h

Source (jump to first uncovered line)
// Copyright (c) 2021-present The Bitcoin Core developers
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.

#ifndef BITCOIN_WALLET_SPEND_H
#define BITCOIN_WALLET_SPEND_H

#include <consensus/amount.h>
#include <policy/fees.h>
#include <util/result.h>
#include <wallet/coinselection.h>
#include <wallet/transaction.h>
#include <wallet/wallet.h>

#include <map>
#include <memory>
#include <optional>
#include <set>
#include <unordered_set>
#include <vector>

namespace wallet {
/** Get the marginal bytes if spending the specified output from this transaction.
 * Use CoinControl to determine whether to expect signature grinding when calculating the size of the input spend. */
int CalculateMaximumSignedInputSize(const CTxOut& txout, const CWallet* pwallet, const CCoinControl* coin_control);
int CalculateMaximumSignedInputSize(const CTxOut& txout, const COutPoint outpoint, const SigningProvider* pwallet, bool can_grind_r, const CCoinControl* coin_control);
struct TxSize {
    int64_t vsize{-1};
    int64_t weight{-1};
};

/** Calculate the size of the transaction using CoinControl to determine
 * whether to expect signature grinding when calculating the size of the input spend. */
TxSize CalculateMaximumSignedTxSize(const CTransaction& tx, const CWallet* wallet, const std::vector<CTxOut>& txouts, const CCoinControl* coin_control = nullptr);
TxSize CalculateMaximumSignedTxSize(const CTransaction& tx, const CWallet* wallet, const CCoinControl* coin_control = nullptr) EXCLUSIVE_LOCKS_REQUIRED(wallet->cs_wallet);

/**
 * COutputs available for spending, stored by OutputType.
 * This struct is really just a wrapper around OutputType vectors with a convenient
 * method for concatenating and returning all COutputs as one vector.
 *
 * Size(), Clear(), Erase(), Shuffle(), and Add() methods are implemented to
 * allow easy interaction with the struct.
 */
struct CoinsResult {
    std::map<OutputType, std::vector<COutput>> coins;

    /** Concatenate and return all COutputs as one vector */
    std::vector<COutput> All() const;

    /** The following methods are provided so that CoinsResult can mimic a vector,
     * i.e., methods can work with individual OutputType vectors or on the entire object */
    size_t Size() const;
    /** Return how many different output types this struct stores */
    size_t TypesCount() const { return coins.size(); }
    void Clear();
    void Erase(const std::unordered_set<COutPoint, SaltedOutpointHasher>& coins_to_remove);
    void Shuffle(FastRandomContext& rng_fast);
    void Add(OutputType type, const COutput& out);

    CAmount GetTotalAmount() { return total_amount; }
    std::optional<CAmount> GetEffectiveTotalAmount() {return total_effective_amount; }

private:
    /** Sum of all available coins raw value */
    CAmount total_amount{0};
    /** Sum of all available coins effective value (each output value minus fees required to spend it) */
    std::optional<CAmount> total_effective_amount{0};
};

struct CoinFilterParams {
    // Outputs below the minimum amount will not get selected
    CAmount min_amount{1};
    // Outputs above the maximum amount will not get selected
    CAmount max_amount{MAX_MONEY};
    // Return outputs until the minimum sum amount is covered
    CAmount min_sum_amount{MAX_MONEY};
    // Maximum number of outputs that can be returned
    uint64_t max_count{0};
    // By default, do not include immature coinbase outputs
    bool include_immature_coinbase{false};
    // By default, skip locked UTXOs
    bool skip_locked{true};
    // When true, filter unconfirmed coins by whether their
    // version's TRUCness matches what is set by CCoinControl.
    bool check_version_trucness{true};
};

/**
 * Populate the CoinsResult struct with vectors of available COutputs, organized by OutputType.
 */
CoinsResult AvailableCoins(const CWallet& wallet,
                           const CCoinControl* coinControl = nullptr,
                           std::optional<CFeeRate> feerate = std::nullopt,
                           const CoinFilterParams& params = {}) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);

/**
 * Find non-change parent output.
 */
const CTxOut& FindNonChangeParentOutput(const CWallet& wallet, const COutPoint& outpoint) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);

/**
 * Return list of available coins and locked coins grouped by non-change output address.
 */
std::map<CTxDestination, std::vector<COutput>> ListCoins(const CWallet& wallet) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);

struct SelectionFilter {
    CoinEligibilityFilter filter;
    bool allow_mixed_output_types{true};
};

/**
* Group coins by the provided filters.
*/
FilteredOutputGroups GroupOutputs(const CWallet& wallet,
                          const CoinsResult& coins,
                          const CoinSelectionParams& coin_sel_params,
                          const std::vector<SelectionFilter>& filters);

/**
 * Attempt to find a valid input set that preserves privacy by not mixing OutputTypes.
 * `ChooseSelectionResult()` will be called on each OutputType individually and the best
 * the solution (according to the waste metric) will be chosen. If a valid input cannot be found from any
 * single OutputType, fallback to running `ChooseSelectionResult()` over all available coins.
 *
 * @param[in]  chain                     The chain interface to get information on bump fees for unconfirmed UTXOs
 * @param[in]  nTargetValue              The target value
 * @param[in]  groups                    The grouped outputs mapped by coin eligibility filters
 * @param[in]  coin_selection_params     Parameters for the coin selection
 * @param[in]  allow_mixed_output_types  Relax restriction that SelectionResults must be of the same OutputType
 * returns                               If successful, a SelectionResult containing the input set
 *                                       If failed, returns (1) an empty error message if the target was not reached (general "Insufficient funds")
 *                                                  or (2) a specific error message if there was something particularly wrong (e.g. a selection
 *                                                  result that surpassed the tx max weight size).
 */
util::Result<SelectionResult> AttemptSelection(interfaces::Chain& chain, const CAmount& nTargetValue, OutputGroupTypeMap& groups,
                        const CoinSelectionParams& coin_selection_params, bool allow_mixed_output_types);

/**
 * Attempt to find a valid input set that meets the provided eligibility filter and target.
 * Multiple coin selection algorithms will be run and the input set that produces the least waste
 * (according to the waste metric) will be chosen.
 *
 * @param[in]  chain                     The chain interface to get information on bump fees for unconfirmed UTXOs
 * @param[in]  nTargetValue              The target value
 * @param[in]  groups                    The struct containing the outputs grouped by script and divided by (1) positive only outputs and (2) all outputs (positive + negative).
 * @param[in]  coin_selection_params     Parameters for the coin selection
 * returns                               If successful, a SelectionResult containing the input set
 *                                       If failed, returns (1) an empty error message if the target was not reached (general "Insufficient funds")
 *                                                  or (2) a specific error message if there was something particularly wrong (e.g. a selection
 *                                                  result that surpassed the tx max weight size).
 */
util::Result<SelectionResult> ChooseSelectionResult(interfaces::Chain& chain, const CAmount& nTargetValue, Groups& groups, const CoinSelectionParams& coin_selection_params);

// User manually selected inputs that must be part of the transaction
struct PreSelectedInputs
{
    std::set<std::shared_ptr<COutput>> coins;
    // If subtract fee from outputs is disabled, the 'total_amount'
    // will be the sum of each output effective value
    // instead of the sum of the outputs amount
    CAmount total_amount{0};

    void Insert(const COutput& output, bool subtract_fee_outputs)
    {
        if (subtract_fee_outputs) {
            total_amount += output.txout.nValue;
        } else {
            total_amount += output.GetEffectiveValue();
        }
        coins.insert(std::make_shared<COutput>(output));
    }
};

/**
 * Fetch and validate coin control selected inputs.
 * Coins could be internal (from the wallet) or external.
*/
util::Result<PreSelectedInputs> FetchSelectedInputs(const CWallet& wallet, const CCoinControl& coin_control,
                                                    const CoinSelectionParams& coin_selection_params) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);

/**
 * Select a set of coins such that nTargetValue is met; never select unconfirmed coins if they are not ours
 * @param[in]   wallet                 The wallet which provides data necessary to spend the selected coins
 * @param[in]   available_coins        The struct of coins, organized by OutputType, available for selection prior to filtering
 * @param[in]   nTargetValue           The target value
 * @param[in]   coin_selection_params  Parameters for this coin selection such as feerates, whether to avoid partial spends,
 *                                     and whether to subtract the fee from the outputs.
 * returns                             If successful, a SelectionResult containing the selected coins
 *                                     If failed, returns (1) an empty error message if the target was not reached (general "Insufficient funds")
 *                                                or (2) an specific error message if there was something particularly wrong (e.g. a selection
 *                                                result that surpassed the tx max weight size).
 */
util::Result<SelectionResult> AutomaticCoinSelection(const CWallet& wallet, CoinsResult& available_coins, const CAmount& nTargetValue,
                 const CoinSelectionParams& coin_selection_params) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);

/**
 * Select all coins from coin_control, and if coin_control 'm_allow_other_inputs=true', call 'AutomaticCoinSelection' to
 * select a set of coins such that nTargetValue - pre_set_inputs.total_amount is met.
 */
util::Result<SelectionResult> SelectCoins(const CWallet& wallet, CoinsResult& available_coins, const PreSelectedInputs& pre_set_inputs,
                                          const CAmount& nTargetValue, const CCoinControl& coin_control,
                                          const CoinSelectionParams& coin_selection_params) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);

struct CreatedTransactionResult
{
    CTransactionRef tx;
    CAmount fee;
    FeeCalculation fee_calc;
    std::optional<unsigned int> change_pos;

    CreatedTransactionResult(CTransactionRef _tx, CAmount _fee, std::optional<unsigned int> _change_pos, const FeeCalculation& _fee_calc)
        : tx(_tx), fee(_fee), fee_calc(_fee_calc), change_pos(_change_pos) {}
};

/**
 * Set a height-based locktime for new transactions (uses the height of the
 * current chain tip unless we are not synced with the current chain
 */
void DiscourageFeeSniping(CMutableTransaction& tx, FastRandomContext& rng_fast, interfaces::Chain& chain, const uint256& block_hash, int block_height);

/**
 * Create a new transaction paying the recipients with a set of coins
 * selected by SelectCoins(); Also create the change output, when needed
 * @note passing change_pos as std::nullopt will result in setting a random position
 */
util::Result<CreatedTransactionResult> CreateTransaction(CWallet& wallet, const std::vector<CRecipient>& vecSend, std::optional<unsigned int> change_pos, const CCoinControl& coin_control, bool sign = true);

/**
 * Insert additional inputs into the transaction by
 * calling CreateTransaction();
 */
util::Result<CreatedTransactionResult> FundTransaction(CWallet& wallet, const CMutableTransaction& tx, const std::vector<CRecipient>& recipients, std::optional<unsigned int> change_pos, bool lockUnspents, CCoinControl);
} // namespace wallet

#endif // BITCOIN_WALLET_SPEND_H

fuzz coverage

Coverage Report

Created: 2025-10-29 15:27

Line	Count	Source (jump to first uncovered line)
1		// Copyright (c) 2021-present The Bitcoin Core developers
2		// Distributed under the MIT software license, see the accompanying
3		// file COPYING or http://www.opensource.org/licenses/mit-license.php.
4
5		#ifndef BITCOIN_WALLET_SPEND_H
6		#define BITCOIN_WALLET_SPEND_H
7
8		#include <consensus/amount.h>
9		#include <policy/fees.h>
10		#include <util/result.h>
11		#include <wallet/coinselection.h>
12		#include <wallet/transaction.h>
13		#include <wallet/wallet.h>
14
15		#include <map>
16		#include <memory>
17		#include <optional>
18		#include <set>
19		#include <unordered_set>
20		#include <vector>
21
22		namespace wallet {
23		/** Get the marginal bytes if spending the specified output from this transaction.
24		* Use CoinControl to determine whether to expect signature grinding when calculating the size of the input spend. */
25		int CalculateMaximumSignedInputSize(const CTxOut& txout, const CWallet* pwallet, const CCoinControl* coin_control);
26		int CalculateMaximumSignedInputSize(const CTxOut& txout, const COutPoint outpoint, const SigningProvider* pwallet, bool can_grind_r, const CCoinControl* coin_control);
27		struct TxSize {
28		int64_t vsize{-1};
29		int64_t weight{-1};
30		};
31
32		/** Calculate the size of the transaction using CoinControl to determine
33		* whether to expect signature grinding when calculating the size of the input spend. */
34		TxSize CalculateMaximumSignedTxSize(const CTransaction& tx, const CWallet* wallet, const std::vector<CTxOut>& txouts, const CCoinControl* coin_control = nullptr);
35		TxSize CalculateMaximumSignedTxSize(const CTransaction& tx, const CWallet* wallet, const CCoinControl* coin_control = nullptr) EXCLUSIVE_LOCKS_REQUIRED(wallet->cs_wallet);
36
37		/**
38		* COutputs available for spending, stored by OutputType.
39		* This struct is really just a wrapper around OutputType vectors with a convenient
40		* method for concatenating and returning all COutputs as one vector.
41		*
42		* Size(), Clear(), Erase(), Shuffle(), and Add() methods are implemented to
43		* allow easy interaction with the struct.
44		*/
45		struct CoinsResult {
46		std::map<OutputType, std::vector<COutput>> coins;
47
48		/** Concatenate and return all COutputs as one vector */
49		std::vector<COutput> All() const;
50
51		/** The following methods are provided so that CoinsResult can mimic a vector,
52		* i.e., methods can work with individual OutputType vectors or on the entire object */
53		size_t Size() const;
54		/** Return how many different output types this struct stores */
55	0	size_t TypesCount() const { return coins.size(); }
56		void Clear();
57		void Erase(const std::unordered_set<COutPoint, SaltedOutpointHasher>& coins_to_remove);
58		void Shuffle(FastRandomContext& rng_fast);
59		void Add(OutputType type, const COutput& out);
60
61	0	CAmount GetTotalAmount() { return total_amount; }
62	0	std::optional<CAmount> GetEffectiveTotalAmount() {return total_effective_amount; }
63
64		private:
65		/** Sum of all available coins raw value */
66		CAmount total_amount{0};
67		/** Sum of all available coins effective value (each output value minus fees required to spend it) */
68		std::optional<CAmount> total_effective_amount{0};
69		};
70
71		struct CoinFilterParams {
72		// Outputs below the minimum amount will not get selected
73		CAmount min_amount{1};
74		// Outputs above the maximum amount will not get selected
75		CAmount max_amount{MAX_MONEY};
76		// Return outputs until the minimum sum amount is covered
77		CAmount min_sum_amount{MAX_MONEY};
78		// Maximum number of outputs that can be returned
79		uint64_t max_count{0};
80		// By default, do not include immature coinbase outputs
81		bool include_immature_coinbase{false};
82		// By default, skip locked UTXOs
83		bool skip_locked{true};
84		// When true, filter unconfirmed coins by whether their
85		// version's TRUCness matches what is set by CCoinControl.
86		bool check_version_trucness{true};
87		};
88
89		/**
90		* Populate the CoinsResult struct with vectors of available COutputs, organized by OutputType.
91		*/
92		CoinsResult AvailableCoins(const CWallet& wallet,
93		const CCoinControl* coinControl = nullptr,
94		std::optional<CFeeRate> feerate = std::nullopt,
95		const CoinFilterParams& params = {}) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);
96
97		/**
98		* Find non-change parent output.
99		*/
100		const CTxOut& FindNonChangeParentOutput(const CWallet& wallet, const COutPoint& outpoint) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);
101
102		/**
103		* Return list of available coins and locked coins grouped by non-change output address.
104		*/
105		std::map<CTxDestination, std::vector<COutput>> ListCoins(const CWallet& wallet) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);
106
107		struct SelectionFilter {
108		CoinEligibilityFilter filter;
109		bool allow_mixed_output_types{true};
110		};
111
112		/**
113		* Group coins by the provided filters.
114		*/
115		FilteredOutputGroups GroupOutputs(const CWallet& wallet,
116		const CoinsResult& coins,
117		const CoinSelectionParams& coin_sel_params,
118		const std::vector<SelectionFilter>& filters);
119
120		/**
121		* Attempt to find a valid input set that preserves privacy by not mixing OutputTypes.
122		* `ChooseSelectionResult()` will be called on each OutputType individually and the best
123		* the solution (according to the waste metric) will be chosen. If a valid input cannot be found from any
124		* single OutputType, fallback to running `ChooseSelectionResult()` over all available coins.
125		*
126		* @param[in] chain The chain interface to get information on bump fees for unconfirmed UTXOs
127		* @param[in] nTargetValue The target value
128		* @param[in] groups The grouped outputs mapped by coin eligibility filters
129		* @param[in] coin_selection_params Parameters for the coin selection
130		* @param[in] allow_mixed_output_types Relax restriction that SelectionResults must be of the same OutputType
131		* returns If successful, a SelectionResult containing the input set
132		* If failed, returns (1) an empty error message if the target was not reached (general "Insufficient funds")
133		* or (2) a specific error message if there was something particularly wrong (e.g. a selection
134		* result that surpassed the tx max weight size).
135		*/
136		util::Result<SelectionResult> AttemptSelection(interfaces::Chain& chain, const CAmount& nTargetValue, OutputGroupTypeMap& groups,
137		const CoinSelectionParams& coin_selection_params, bool allow_mixed_output_types);
138
139		/**
140		* Attempt to find a valid input set that meets the provided eligibility filter and target.
141		* Multiple coin selection algorithms will be run and the input set that produces the least waste
142		* (according to the waste metric) will be chosen.
143		*
144		* @param[in] chain The chain interface to get information on bump fees for unconfirmed UTXOs
145		* @param[in] nTargetValue The target value
146		* @param[in] groups The struct containing the outputs grouped by script and divided by (1) positive only outputs and (2) all outputs (positive + negative).
147		* @param[in] coin_selection_params Parameters for the coin selection
148		* returns If successful, a SelectionResult containing the input set
149		* If failed, returns (1) an empty error message if the target was not reached (general "Insufficient funds")
150		* or (2) a specific error message if there was something particularly wrong (e.g. a selection
151		* result that surpassed the tx max weight size).
152		*/
153		util::Result<SelectionResult> ChooseSelectionResult(interfaces::Chain& chain, const CAmount& nTargetValue, Groups& groups, const CoinSelectionParams& coin_selection_params);
154
155		// User manually selected inputs that must be part of the transaction
156		struct PreSelectedInputs
157		{
158		std::set<std::shared_ptr<COutput>> coins;
159		// If subtract fee from outputs is disabled, the 'total_amount'
160		// will be the sum of each output effective value
161		// instead of the sum of the outputs amount
162		CAmount total_amount{0};
163
164		void Insert(const COutput& output, bool subtract_fee_outputs)
165	0	{
166	0	if (subtract_fee_outputs) {
167	0	total_amount += output.txout.nValue;
168	0	} else {
169	0	total_amount += output.GetEffectiveValue();
170	0	}
171	0	coins.insert(std::make_shared<COutput>(output));
172	0	}
173		};
174
175		/**
176		* Fetch and validate coin control selected inputs.
177		* Coins could be internal (from the wallet) or external.
178		*/
179		util::Result<PreSelectedInputs> FetchSelectedInputs(const CWallet& wallet, const CCoinControl& coin_control,
180		const CoinSelectionParams& coin_selection_params) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);
181
182		/**
183		* Select a set of coins such that nTargetValue is met; never select unconfirmed coins if they are not ours
184		* @param[in] wallet The wallet which provides data necessary to spend the selected coins
185		* @param[in] available_coins The struct of coins, organized by OutputType, available for selection prior to filtering
186		* @param[in] nTargetValue The target value
187		* @param[in] coin_selection_params Parameters for this coin selection such as feerates, whether to avoid partial spends,
188		* and whether to subtract the fee from the outputs.
189		* returns If successful, a SelectionResult containing the selected coins
190		* If failed, returns (1) an empty error message if the target was not reached (general "Insufficient funds")
191		* or (2) an specific error message if there was something particularly wrong (e.g. a selection
192		* result that surpassed the tx max weight size).
193		*/
194		util::Result<SelectionResult> AutomaticCoinSelection(const CWallet& wallet, CoinsResult& available_coins, const CAmount& nTargetValue,
195		const CoinSelectionParams& coin_selection_params) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);
196
197		/**
198		* Select all coins from coin_control, and if coin_control 'm_allow_other_inputs=true', call 'AutomaticCoinSelection' to
199		* select a set of coins such that nTargetValue - pre_set_inputs.total_amount is met.
200		*/
201		util::Result<SelectionResult> SelectCoins(const CWallet& wallet, CoinsResult& available_coins, const PreSelectedInputs& pre_set_inputs,
202		const CAmount& nTargetValue, const CCoinControl& coin_control,
203		const CoinSelectionParams& coin_selection_params) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);
204
205		struct CreatedTransactionResult
206		{
207		CTransactionRef tx;
208		CAmount fee;
209		FeeCalculation fee_calc;
210		std::optional<unsigned int> change_pos;
211
212		CreatedTransactionResult(CTransactionRef _tx, CAmount _fee, std::optional<unsigned int> _change_pos, const FeeCalculation& _fee_calc)
213	0	: tx(_tx), fee(_fee), fee_calc(_fee_calc), change_pos(_change_pos) {}
214		};
215
216		/**
217		* Set a height-based locktime for new transactions (uses the height of the
218		* current chain tip unless we are not synced with the current chain
219		*/
220		void DiscourageFeeSniping(CMutableTransaction& tx, FastRandomContext& rng_fast, interfaces::Chain& chain, const uint256& block_hash, int block_height);
221
222		/**
223		* Create a new transaction paying the recipients with a set of coins
224		* selected by SelectCoins(); Also create the change output, when needed
225		* @note passing change_pos as std::nullopt will result in setting a random position
226		*/
227		util::Result<CreatedTransactionResult> CreateTransaction(CWallet& wallet, const std::vector<CRecipient>& vecSend, std::optional<unsigned int> change_pos, const CCoinControl& coin_control, bool sign = true);
228
229		/**
230		* Insert additional inputs into the transaction by
231		* calling CreateTransaction();
232		*/
233		util::Result<CreatedTransactionResult> FundTransaction(CWallet& wallet, const CMutableTransaction& tx, const std::vector<CRecipient>& recipients, std::optional<unsigned int> change_pos, bool lockUnspents, CCoinControl);
234		} // namespace wallet
235
236		#endif // BITCOIN_WALLET_SPEND_H