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.

22,396 bytes · SHA-256 edaf87098a5dfaa5… · View upstream ↗

1// Copyright (c) 2017-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_COINSELECTION_H
6#define BITCOIN_WALLET_COINSELECTION_H
7
8#include <consensus/amount.h>
9#include <consensus/consensus.h>
10#include <outputtype.h>
11#include <policy/feerate.h>
12#include <primitives/transaction.h>
13#include <random.h>
14#include <util/check.h>
15#include <util/insert.h>
16#include <util/result.h>
17
18#include <optional>
19
20
21namespace wallet {
22//! lower bound for randomly-chosen target change amount
23inline constexpr CAmount CHANGE_LOWER{50'000};
24//! upper bound for randomly-chosen target change amount
25inline constexpr CAmount CHANGE_UPPER{1'000'000};
26
27/** A UTXO under consideration for use in funding a new transaction. */
28struct COutput {
29private:
30    /** The output's value minus fees required to spend it and bump its unconfirmed ancestors to the target feerate. */
31    std::optional<CAmount> effective_value;
32
33    /** The fee required to spend this output at the transaction's target feerate and to bump its unconfirmed ancestors to the target feerate. */
34    std::optional<CAmount> fee;
35
36public:
37    /** The outpoint identifying this UTXO */
38    COutPoint outpoint;
39
40    /** The output itself */
41    CTxOut txout;
42
43    /**
44     * Depth in block chain.
45     * If > 0: the tx is on chain and has this many confirmations.
46     * If = 0: the tx is waiting confirmation.
47     * If < 0: a conflicting tx is on chain and has this many confirmations. */
48    int depth;
49
50    /** Pre-computed estimated size of this output as a fully-signed input in a transaction. Can be -1 if it could not be calculated */
51    int input_bytes;
52
53    /** Whether we know how to spend this output, ignoring the lack of keys */
54    bool solvable;
55
56    /**
57     * Whether this output is considered safe to spend. Unconfirmed transactions
58     * from outside keys and unconfirmed replacement transactions are considered
59     * unsafe and will not be used to fund new spending transactions.
60     */
61    bool safe;
62
63    /** The time of the transaction containing this output as determined by CWalletTx::nTimeSmart */
64    int64_t time;
65
66    /** Whether the transaction containing this output is sent from the owning wallet */
67    bool from_me;
68
69    /** The fee required to spend this output at the consolidation feerate. */
70    CAmount long_term_fee{0};
71
72    /** The fee necessary to bump this UTXO's ancestor transactions to the target feerate */
73    CAmount ancestor_bump_fees{0};
74
75    COutput(const COutPoint& outpoint, const CTxOut& txout, int depth, int input_bytes, bool solvable, bool safe, int64_t time, bool from_me, const std::optional<CFeeRate> feerate = std::nullopt)
76        : outpoint{outpoint},
77          txout{txout},
78          depth{depth},
79          input_bytes{input_bytes},
80          solvable{solvable},
81          safe{safe},
82          time{time},
83          from_me{from_me}
84    {
85        if (feerate) {
86            // base fee without considering potential unconfirmed ancestors
87            fee = input_bytes < 0 ? 0 : feerate.value().GetFee(input_bytes);
88            effective_value = txout.nValue - fee.value();
89        }
90    }
91
92    COutput(const COutPoint& outpoint, const CTxOut& txout, int depth, int input_bytes, bool solvable, bool safe, int64_t time, bool from_me, const CAmount fees)
93        : COutput(outpoint, txout, depth, input_bytes, solvable, safe, time, from_me)
94    {
95        // if input_bytes is unknown, then fees should be 0, if input_bytes is known, then the fees should be a positive integer or 0 (input_bytes known and fees = 0 only happens in the tests)
96        assert((input_bytes < 0 && fees == 0) || (input_bytes > 0 && fees >= 0));
97        fee = fees;
98        effective_value = txout.nValue - fee.value();
99    }
100
101    bool operator<(const COutput& rhs) const
102    {
103        return outpoint < rhs.outpoint;
104    }
105
106    void ApplyBumpFee(CAmount bump_fee)
107    {
108        assert(bump_fee >= 0);
109        ancestor_bump_fees = bump_fee;
110        assert(fee);
111        *fee += bump_fee;
112        // Note: assert(effective_value - bump_fee == nValue - fee.value());
113        effective_value = txout.nValue - fee.value();
114    }
115
116    CAmount GetFee() const
117    {
118        assert(fee.has_value());
119        return fee.value();
120    }
121
122    CAmount GetEffectiveValue() const
123    {
124        assert(effective_value.has_value());
125        return effective_value.value();
126    }
127
128    bool HasEffectiveValue() const { return effective_value.has_value(); }
129};
130
131/** Parameters for one iteration of Coin Selection. */
132struct CoinSelectionParams {
133    /** Randomness to use in the context of coin selection. */
134    FastRandomContext& rng_fast;
135    /** Size of a change output in bytes, determined by the output type. */
136    int change_output_size = 0;
137    /** Size of the input to spend a change output in virtual bytes. */
138    int change_spend_size = 0;
139    /** Mininmum change to target in Knapsack solver and CoinGrinder:
140     * select coins to cover the payment and at least this value of change. */
141    CAmount m_min_change_target{0};
142    /** Minimum amount for creating a change output.
143     * If change budget is smaller than min_change then we forgo creation of change output.
144     */
145    CAmount min_viable_change{0};
146    /** Cost of creating the change output. */
147    CAmount m_change_fee{0};
148    /** Cost of creating the change output + cost of spending the change output in the future. */
149    CAmount m_cost_of_change{0};
150    /** The targeted feerate of the transaction being built. */
151    CFeeRate m_effective_feerate;
152    /** The feerate estimate used to estimate an upper bound on what should be sufficient to spend
153     * the change output sometime in the future. */
154    CFeeRate m_long_term_feerate;
155    /** If the cost to spend a change output at the discard feerate exceeds its value, drop it to fees. */
156    CFeeRate m_discard_feerate;
157    /** Size of the transaction before coin selection, consisting of the header and recipient
158     * output(s), excluding the inputs and change output(s). */
159    int tx_noinputs_size = 0;
160    /** Indicate that we are subtracting the fee from outputs */
161    bool m_subtract_fee_outputs = false;
162    /** When true, always spend all (up to OUTPUT_GROUP_MAX_ENTRIES) or none of the outputs
163     * associated with the same address. This helps reduce privacy leaks resulting from address
164     * reuse. Dust outputs are not eligible to be added to output groups and thus not considered. */
165    bool m_avoid_partial_spends = false;
166    /**
167     * When true, allow unsafe coins to be selected during Coin Selection. This may spend unconfirmed outputs:
168     * 1) Received from other wallets, 2) replacing other txs, 3) that have been replaced.
169     */
170    bool m_include_unsafe_inputs = false;
171    /** The version of the transaction we are trying to create. */
172    uint32_t m_version{CTransaction::CURRENT_VERSION};
173    /** The maximum weight for this transaction. */
174    std::optional<int> m_max_tx_weight{std::nullopt};
175
176    CoinSelectionParams(FastRandomContext& rng_fast, int change_output_size, int change_spend_size,
177                        CAmount min_change_target, CFeeRate effective_feerate,
178                        CFeeRate long_term_feerate, CFeeRate discard_feerate, int tx_noinputs_size, bool avoid_partial,
179                        std::optional<int> max_tx_weight = std::nullopt)
180        : rng_fast{rng_fast},
181          change_output_size(change_output_size),
182          change_spend_size(change_spend_size),
183          m_min_change_target(min_change_target),
184          m_effective_feerate(effective_feerate),
185          m_long_term_feerate(long_term_feerate),
186          m_discard_feerate(discard_feerate),
187          tx_noinputs_size(tx_noinputs_size),
188          m_avoid_partial_spends(avoid_partial),
189          m_max_tx_weight(max_tx_weight)
190    {
191    }
192    CoinSelectionParams(FastRandomContext& rng_fast)
193        : rng_fast{rng_fast} {}
194};
195
196/** Parameters for filtering which OutputGroups we may use in coin selection.
197 * We start by being very selective and requiring multiple confirmations and
198 * then get more permissive if we cannot fund the transaction. */
199struct CoinEligibilityFilter
200{
201    /** Minimum number of confirmations for outputs that we sent to ourselves.
202     * We may use unconfirmed UTXOs sent from ourselves, e.g. change outputs. */
203    const int conf_mine;
204    /** Minimum number of confirmations for outputs received from a different wallet. */
205    const int conf_theirs;
206    /** Maximum number of unconfirmed ancestors aggregated across all UTXOs in an OutputGroup. */
207    const uint64_t max_ancestors;
208    /** Maximum cluster count that a single UTXO in the OutputGroup may have. In practice, this filter also caps the
209     * maximum descendant count, as a transaction's descendant count is never larger than its cluster count. */
210    const uint64_t max_cluster_count;
211    /** When avoid_reuse=true and there are full groups (OUTPUT_GROUP_MAX_ENTRIES), whether or not to use any partial groups.*/
212    const bool m_include_partial_groups{false};
213
214    CoinEligibilityFilter() = delete;
215    CoinEligibilityFilter(int conf_mine, int conf_theirs, uint64_t max_ancestors) : conf_mine(conf_mine), conf_theirs(conf_theirs), max_ancestors(max_ancestors), max_cluster_count(max_ancestors) {}
216    CoinEligibilityFilter(int conf_mine, int conf_theirs, uint64_t max_ancestors, uint64_t max_cluster_count) : conf_mine(conf_mine), conf_theirs(conf_theirs), max_ancestors(max_ancestors), max_cluster_count(max_cluster_count) {}
217    CoinEligibilityFilter(int conf_mine, int conf_theirs, uint64_t max_ancestors, uint64_t max_cluster_count, bool include_partial) : conf_mine(conf_mine), conf_theirs(conf_theirs), max_ancestors(max_ancestors), max_cluster_count(max_cluster_count), m_include_partial_groups(include_partial) {}
218
219    bool operator<(const CoinEligibilityFilter& other) const {
220        return std::tie(conf_mine, conf_theirs, max_ancestors, max_cluster_count, m_include_partial_groups)
221               < std::tie(other.conf_mine, other.conf_theirs, other.max_ancestors, other.max_cluster_count, other.m_include_partial_groups);
222    }
223};
224
225/** A group of UTXOs paid to the same output script. */
226struct OutputGroup
227{
228    /** The list of UTXOs contained in this output group. */
229    std::vector<std::shared_ptr<COutput>> m_outputs;
230    /** Whether the UTXOs were sent by the wallet to itself. This is relevant because we may want at
231     * least a certain number of confirmations on UTXOs received from outside wallets while trusting
232     * our own UTXOs more. */
233    bool m_from_me{true};
234    /** The total value of the UTXOs in sum. */
235    CAmount m_value{0};
236    /** The minimum number of confirmations the UTXOs in the group have. Unconfirmed is 0. */
237    int m_depth{999};
238    /** The aggregated count of unconfirmed ancestors of all UTXOs in this
239     * group. Not deduplicated and may overestimate when ancestors are shared. */
240    size_t m_ancestors{0};
241    /** The maximum cluster count of a single UTXO in this output group. */
242    size_t m_max_cluster_count{0};
243    /** The value of the UTXOs after deducting the cost of spending them at the effective feerate. */
244    CAmount effective_value{0};
245    /** The fee to spend these UTXOs at the effective feerate. */
246    CAmount fee{0};
247    /** The fee to spend these UTXOs at the long term feerate. */
248    CAmount long_term_fee{0};
249    /** The feerate for spending a created change output eventually (i.e. not urgently, and thus at
250     * a lower feerate). Calculated using long term fee estimate. This is used to decide whether

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.