READ THE CODE

Inside Bitcoin

The code behind the network, with room to understand it.

Stable release v32.1bitcoin/bitcoin · f0de87f04062 ↗3,020 source files · 47.5 MB stored on the server340 file guides

Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.

11,574 bytes · SHA-256 424aecd50034084d… · View upstream ↗

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 <util/result.h>
10#include <wallet/coinselection.h>
11#include <wallet/transaction.h>
12#include <wallet/types.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
22namespace 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. */
25int CalculateMaximumSignedInputSize(const CTxOut& txout, const CWallet* pwallet, const CCoinControl* coin_control);
26int CalculateMaximumSignedInputSize(const CTxOut& txout, COutPoint outpoint, const SigningProvider* pwallet, bool can_grind_r, const CCoinControl* coin_control);
27struct 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. */
34TxSize CalculateMaximumSignedTxSize(const CTransaction& tx, const CWallet* wallet, const std::vector<CTxOut>& txouts, const CCoinControl* coin_control = nullptr);
35TxSize 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(), Erase(), Shuffle(), and Add() methods are implemented to
43 * allow easy interaction with the struct.
44 */
45struct 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    size_t TypesCount() const { return coins.size(); }
56    void Erase(const std::unordered_set<COutPoint, SaltedOutpointHasher>& coins_to_remove);
57    void Shuffle(FastRandomContext& rng_fast);
58    void Add(OutputType type, const COutput& out);
59
60    CAmount GetTotalAmount() const { return total_amount; }
61    std::optional<CAmount> GetEffectiveTotalAmount() const { return total_effective_amount; }
62    // Returns the appropriate total based on whether fees are being subtracted from outputs
63    std::optional<CAmount> GetAppropriateTotal(bool subtract_fee_outputs) const {
64        return subtract_fee_outputs ? total_amount : total_effective_amount;
65    }
66
67private:
68    /** Sum of all available coins raw value */
69    CAmount total_amount{0};
70    /** Sum of all available coins effective value (each output value minus fees required to spend it) */
71    std::optional<CAmount> total_effective_amount;
72};
73
74struct CoinFilterParams {
75    // Outputs below the minimum amount will not get selected
76    CAmount min_amount{1};
77    // Outputs above the maximum amount will not get selected
78    CAmount max_amount{MAX_MONEY};
79    // Return outputs until the minimum sum amount is covered
80    CAmount min_sum_amount{MAX_MONEY};
81    // Maximum number of outputs that can be returned
82    uint64_t max_count{0};
83    // By default, do not include immature coinbase outputs
84    bool include_immature_coinbase{false};
85    // By default, skip locked UTXOs
86    bool skip_locked{true};
87    // When true, filter unconfirmed coins by whether their
88    // version's TRUCness matches what is set by CCoinControl.
89    bool check_version_trucness{true};
90};
91
92/**
93 * Populate the CoinsResult struct with vectors of available COutputs, organized by OutputType.
94 */
95CoinsResult AvailableCoins(const CWallet& wallet,
96                           const CCoinControl* coinControl = nullptr,
97                           std::optional<CFeeRate> feerate = std::nullopt,
98                           const CoinFilterParams& params = {}) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);
99
100/**
101 * Find non-change parent output.
102 */
103const CTxOut& FindNonChangeParentOutput(const CWallet& wallet, const COutPoint& outpoint) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);
104
105/**
106 * Return list of available coins and locked coins grouped by non-change output address.
107 */
108std::map<CTxDestination, std::vector<COutput>> ListCoins(const CWallet& wallet) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);
109
110struct SelectionFilter {
111    CoinEligibilityFilter filter;
112    bool allow_mixed_output_types{true};
113};
114
115/**
116* Group coins by the provided filters.
117*/
118FilteredOutputGroups GroupOutputs(const CWallet& wallet,
119                          const CoinsResult& coins,
120                          const CoinSelectionParams& coin_sel_params,
121                          const std::vector<SelectionFilter>& filters);
122
123/**
124 * Attempt to find a valid input set that preserves privacy by not mixing OutputTypes.
125 * `ChooseSelectionResult()` will be called on each OutputType individually and the best
126 * the solution (according to the waste metric) will be chosen. If a valid input cannot be found from any
127 * single OutputType, fallback to running `ChooseSelectionResult()` over all available coins.
128 *
129 * @param[in]  chain                     The chain interface to get information on bump fees for unconfirmed UTXOs
130 * @param[in]  nTargetValue              The target value
131 * @param[in]  groups                    The grouped outputs mapped by coin eligibility filters
132 * @param[in]  coin_selection_params     Parameters for the coin selection
133 * @param[in]  allow_mixed_output_types  Relax restriction that SelectionResults must be of the same OutputType
134 * returns                               If successful, a SelectionResult containing the input set
135 *                                       If failed, returns (1) an empty error message if the target was not reached (general "Insufficient funds")
136 *                                                  or (2) a specific error message if there was something particularly wrong (e.g. a selection
137 *                                                  result that surpassed the tx max weight size).
138 */
139util::Result<SelectionResult> AttemptSelection(interfaces::Chain& chain, const CAmount& nTargetValue, OutputGroupTypeMap& groups,
140                        const CoinSelectionParams& coin_selection_params, bool allow_mixed_output_types);
141
142/**
143 * Attempt to find a valid input set that meets the provided eligibility filter and target.
144 * Multiple coin selection algorithms will be run and the input set that produces the least waste
145 * (according to the waste metric) will be chosen.
146 *
147 * @param[in]  chain                     The chain interface to get information on bump fees for unconfirmed UTXOs
148 * @param[in]  nTargetValue              The target value
149 * @param[in]  groups                    The struct containing the outputs grouped by script and divided by (1) positive only outputs and (2) all outputs (positive + negative).
150 * @param[in]  coin_selection_params     Parameters for the coin selection
151 * returns                               If successful, a SelectionResult containing the input set
152 *                                       If failed, returns (1) an empty error message if the target was not reached (general "Insufficient funds")
153 *                                                  or (2) a specific error message if there was something particularly wrong (e.g. a selection
154 *                                                  result that surpassed the tx max weight size).
155 */
156util::Result<SelectionResult> ChooseSelectionResult(interfaces::Chain& chain, const CAmount& nTargetValue, Groups& groups, const CoinSelectionParams& coin_selection_params);
157
158/**
159 * Fetch and validate coin control selected inputs.
160 * Coins could be internal (from the wallet) or external.
161*/
162util::Result<CoinsResult> FetchSelectedInputs(const CWallet& wallet, const CCoinControl& coin_control,
163                                                    const CoinSelectionParams& coin_selection_params) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);
164
165/**
166 * Select a set of coins such that nTargetValue is met; never select unconfirmed coins if they are not ours
167 * @param[in]   wallet                 The wallet which provides data necessary to spend the selected coins
168 * @param[in]   available_coins        The struct of coins, organized by OutputType, available for selection prior to filtering
169 * @param[in]   nTargetValue           The target value
170 * @param[in]   coin_selection_params  Parameters for this coin selection such as feerates, whether to avoid partial spends,
171 *                                     and whether to subtract the fee from the outputs.
172 * returns                             If successful, a SelectionResult containing the selected coins
173 *                                     If failed, returns (1) an empty error message if the target was not reached (general "Insufficient funds")
174 *                                                or (2) an specific error message if there was something particularly wrong (e.g. a selection
175 *                                                result that surpassed the tx max weight size).
176 */
177util::Result<SelectionResult> AutomaticCoinSelection(const CWallet& wallet, CoinsResult& available_coins, const CAmount& nTargetValue,
178                 const CoinSelectionParams& coin_selection_params) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);
179
180/**
181 * Select all coins from coin_control, and if coin_control 'm_allow_other_inputs=true', call 'AutomaticCoinSelection' to
182 * select a set of coins such that nTargetValue - pre_set_inputs.total_amount is met.
183 */
184util::Result<SelectionResult> SelectCoins(const CWallet& wallet, CoinsResult& available_coins, const CoinsResult& pre_set_inputs,
185                                          const CAmount& nTargetValue, const CCoinControl& coin_control,
186                                          const CoinSelectionParams& coin_selection_params) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet);
187
188/**
189 * Set a height-based locktime for new transactions (uses the height of the
190 * current chain tip unless we are not synced with the current chain
191 */
192void DiscourageFeeSniping(CMutableTransaction& tx, FastRandomContext& rng_fast, interfaces::Chain& chain, const uint256& block_hash, int block_height);
193
194/**
195 * Create a new transaction paying the recipients with a set of coins
196 * selected by SelectCoins(); Also create the change output, when needed
197 * @note passing change_pos as std::nullopt will result in setting a random position
198 */
199util::Result<CreatedTransactionResult> CreateTransaction(CWallet& wallet, const std::vector<CRecipient>& vecSend, std::optional<unsigned int> change_pos, const CCoinControl& coin_control, bool sign = true);
200
201/**
202 * Insert additional inputs into the transaction by
203 * calling CreateTransaction();
204 */
205util::Result<CreatedTransactionResult> FundTransaction(CWallet& wallet, const CMutableTransaction& tx, const std::vector<CRecipient>& recipients, std::optional<unsigned int> change_pos, bool lockUnspents, CCoinControl);
206} // namespace wallet
207
208#endif // BITCOIN_WALLET_SPEND_H
209

src/wallet/receive.cpp

src/wallet/coinselection.cpp

src/consensus/validation.h

src/primitives/transaction.cpp

src/script/descriptor.cpp

src/bitcoin-cli.cpp

src/rpc/blockchain.cpp

src/rpc/rawtransaction.cpp

src/init.cpp

src/crypto/sha256.cpp

src/consensus/merkle.h

src/consensus/tx_check.h

src/consensus/tx_verify.h

src/policy/feerate.h

src/policy/feerate.cpp

src/primitives/transaction_identifier.h

src/chainparamsbase.h

src/chainparamsbase.cpp

src/util/moneystr.cpp

src/crypto/ripemd160.h

src/crypto/sha1.h

src/crypto/sha512.h

src/crypto/hmac_sha256.h

src/crypto/hmac_sha512.h

src/crypto/hmac_sha256.cpp

src/crypto/hmac_sha512.cpp

src/crypto/hkdf_sha256_32.h

src/crypto/hkdf_sha256_32.cpp

src/support/cleanse.h

src/support/cleanse.cpp

src/crypto/siphash.cpp

src/crypto/muhash.h

src/crypto/chacha20.h

src/crypto/poly1305.h

src/crypto/chacha20poly1305.h

src/crypto/chacha20poly1305.cpp

src/util/chaintype.cpp

src/util/obfuscation.h

src/util/byte_units.h

src/util/overflow.h

src/blockencodings.cpp

src/net_permissions.cpp

src/policy/packages.cpp

src/policy/rbf.cpp

src/policy/truc_policy.cpp

src/policy/ephemeral_policy.cpp

src/policy/settings.cpp

src/policy/policy.cpp

src/node/transaction.cpp

src/node/coin.cpp

src/rpc/client.cpp

src/rpc/external_signer.cpp

src/rpc/request.cpp

src/rpc/server_util.cpp

src/rpc/fees.cpp

src/rpc/output_script.cpp

src/rpc/rawtransaction_util.cpp

src/rpc/rawtransaction_util.h

src/rpc/register.h

src/rpc/request.h

src/rpc/server_util.h

src/rpc/protocol.h

src/rpc/server.h

src/rpc/signmessage.cpp

src/rpc/txoutproof.cpp

src/rpc/util.cpp

src/rpc/util.h

src/wallet/rpc/addresses.cpp

src/wallet/rpc/backup.cpp

src/wallet/rpc/coins.cpp

src/wallet/rpc/encrypt.cpp

src/wallet/rpc/signmessage.cpp

src/wallet/rpc/util.cpp

src/wallet/rpc/util.h

src/wallet/coincontrol.cpp

src/wallet/coincontrol.h

src/wallet/context.cpp

src/wallet/context.h

src/wallet/crypter.cpp

src/wallet/crypter.h

src/wallet/db.cpp

src/wallet/export.cpp

src/wallet/external_signer_scriptpubkeyman.cpp

src/wallet/rpc/spend.cpp

src/wallet/rpc/transactions.cpp

src/wallet/rpc/wallet.cpp

src/wallet/feebumper.cpp

src/wallet/feebumper.h

src/index/base.h

src/index/base.cpp

src/index/txindex.h

src/index/txindex.cpp

src/index/txindex_key.h

src/index/txospenderindex.h

src/index/txospenderindex.cpp

src/index/blockfilterindex.h

src/index/blockfilterindex.cpp

src/index/coinstatsindex.h

src/index/coinstatsindex.cpp

src/index/db_key.h

src/index/disktxpos.h

src/kernel/chain.cpp

src/kernel/chain.h

src/kernel/checks.cpp

src/kernel/checks.h

src/kernel/context.cpp

src/kernel/context.h

src/kernel/cs_main.cpp

src/kernel/cs_main.h

src/kernel/disconnected_transactions.cpp

src/kernel/disconnected_transactions.h

src/kernel/mempool_removal_reason.cpp

src/kernel/mempool_removal_reason.h

src/kernel/coinstats.cpp

src/kernel/coinstats.h

src/kernel/chainparams.cpp

src/kernel/chainparams.h

src/wallet/sqlite.cpp

src/wallet/sqlite.h

src/wallet/transaction.cpp

src/wallet/transaction.h

src/wallet/dump.cpp

src/wallet/dump.h

src/wallet/init.cpp

src/wallet/walletutil.cpp

src/wallet/walletutil.h

src/wallet/wallettool.cpp

src/wallet/wallettool.h

src/wallet/export.h

src/wallet/migrate.cpp

src/wallet/migrate.h

src/wallet/db.h

src/wallet/walletdb.cpp

src/wallet/interfaces.cpp

src/wallet/scriptpubkeyman.cpp

src/wallet/scriptpubkeyman.h

src/kernel/bitcoinkernel.cpp

src/kernel/bitcoinkernel.h

src/kernel/bitcoinkernel_wrapper.h

src/node/chainstate.cpp

src/node/chainstate.h

src/node/blockstorage.cpp

src/node/blockstorage.h

src/node/mempool_persist.cpp

src/node/mempool_persist.h

src/node/utxo_snapshot.cpp

src/node/utxo_snapshot.h

src/node/kernel_notifications.cpp

src/node/kernel_notifications.h

src/node/blockmanager_args.cpp

src/kernel/blockmanager_opts.h

src/util/expected.cpp

src/policy/settings.h

src/util/types.h

src/kernel/messagestartchars.h

src/kernel/warning.h

src/util/exception.h

src/common/license_info.h

src/node/coins_view_args.h

src/node/database_args.h

src/util/batchpriority.h

src/util/ui_change_type.h

src/node/coins_view_args.cpp

src/node/peerman_args.h

src/util/serfloat.h

src/node/blockmanager_args.h

src/node/database_args.cpp

src/util/overloaded.h

src/interfaces/types.h

src/node/chainstatemanager_args.h

src/node/minisketchwrapper.h

src/util/macros.h

src/util/syserror.h

src/common/run_command.h

src/util/bytevectorhash.cpp

src/node/mempool_persist_args.cpp

src/util/exec.h

src/util/rbf.h

src/crypto/hex_base.h

src/node/mempool_persist_args.h

src/interfaces/echo.h

src/util/any.h

src/util/batchpriority.cpp

src/util/threadnames.h

src/node/coin.h

src/node/mempool_args.h

src/util/asmap.h

src/util/bytevectorhash.h

src/node/context.cpp

src/util/insert.h

src/util/readwritefile.h

src/node/peerman_args.cpp

src/node/interface_ui.cpp

src/interfaces/handler.h

src/node/mining_args.h

src/util/hasher.cpp

src/common/init.h

src/kernel/mempool_limits.h

src/common/system.h

src/crypto/sha3.h

src/util/threadinterrupt.cpp

src/node/protocol_version.h

src/util/exception.cpp

src/common/messages.h

src/node/connection_types.cpp

src/util/bip32.h

src/common/license_info.cpp

src/util/stdmutex.h

src/common/run_command.cpp

src/util/check.cpp

src/util/golombrice.h

src/node/types.h

src/node/timeoffsets.h

src/util/readwritefile.cpp

src/util/fastrange.h

src/util/signalinterrupt.h

src/util/task_runner.h

src/util/syserror.cpp

src/common/interfaces.cpp

src/common/types.h

src/util/threadinterrupt.h

src/kernel/chainstatemanager_opts.h

src/node/psbt.h

src/policy/ephemeral_policy.h

src/util/trace.h

src/common/url.cpp

src/kernel/mempool_options.h

src/util/serfloat.cpp

src/kernel/notifications_interface.h

src/node/timeoffsets.cpp

src/node/warnings.cpp

src/util/hash_type.h

src/crypto/hex_base.cpp

src/node/eviction.h

src/util/tokenbucket.h

src/crypto/aes.h

src/common/pcp.h

src/util/feefrac.cpp

src/node/transaction.h

src/util/threadnames.cpp

src/common/signmessage.h

src/util/exec.cpp

src/util/signalinterrupt.cpp

Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.

Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.