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 21 namespace wallet {
22 //! lower bound for randomly-chosen target change amount
23 static constexpr CAmount CHANGE_LOWER{50000};
24 //! upper bound for randomly-chosen target change amount
25 static constexpr CAmount CHANGE_UPPER{1000000};
26 27 /** A UTXO under consideration for use in funding a new transaction. */
28 struct COutput {
29 private:
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 36 public:
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 std::string ToString() const;
102 103 bool operator<(const COutput& rhs) const
104 {
105 return outpoint < rhs.outpoint;
106 }
107 108 void ApplyBumpFee(CAmount bump_fee)
109 {
110 assert(bump_fee >= 0);
111 ancestor_bump_fees = bump_fee;
112 assert(fee);
113 *fee += bump_fee;
114 // Note: assert(effective_value - bump_fee == nValue - fee.value());
115 effective_value = txout.nValue - fee.value();
116 }
117 118 CAmount GetFee() const
119 {
120 assert(fee.has_value());
121 return fee.value();
122 }
123 124 CAmount GetEffectiveValue() const
125 {
126 assert(effective_value.has_value());
127 return effective_value.value();
128 }
129 130 bool HasEffectiveValue() const { return effective_value.has_value(); }
131 };
132 133 /** Parameters for one iteration of Coin Selection. */
134 struct CoinSelectionParams {
135 /** Randomness to use in the context of coin selection. */
136 FastRandomContext& rng_fast;
137 /** Size of a change output in bytes, determined by the output type. */
138 int change_output_size = 0;
139 /** Size of the input to spend a change output in virtual bytes. */
140 int change_spend_size = 0;
141 /** Mininmum change to target in Knapsack solver and CoinGrinder:
142 * select coins to cover the payment and at least this value of change. */
143 CAmount m_min_change_target{0};
144 /** Minimum amount for creating a change output.
145 * If change budget is smaller than min_change then we forgo creation of change output.
146 */
147 CAmount min_viable_change{0};
148 /** Cost of creating the change output. */
149 CAmount m_change_fee{0};
150 /** Cost of creating the change output + cost of spending the change output in the future. */
151 CAmount m_cost_of_change{0};
152 /** The targeted feerate of the transaction being built. */
153 CFeeRate m_effective_feerate;
154 /** The feerate estimate used to estimate an upper bound on what should be sufficient to spend
155 * the change output sometime in the future. */
156 CFeeRate m_long_term_feerate;
157 /** If the cost to spend a change output at the discard feerate exceeds its value, drop it to fees. */
158 CFeeRate m_discard_feerate;
159 /** Size of the transaction before coin selection, consisting of the header and recipient
160 * output(s), excluding the inputs and change output(s). */
161 int tx_noinputs_size = 0;
162 /** Indicate that we are subtracting the fee from outputs */
163 bool m_subtract_fee_outputs = false;
164 /** When true, always spend all (up to OUTPUT_GROUP_MAX_ENTRIES) or none of the outputs
165 * associated with the same address. This helps reduce privacy leaks resulting from address
166 * reuse. Dust outputs are not eligible to be added to output groups and thus not considered. */
167 bool m_avoid_partial_spends = false;
168 /**
169 * When true, allow unsafe coins to be selected during Coin Selection. This may spend unconfirmed outputs:
170 * 1) Received from other wallets, 2) replacing other txs, 3) that have been replaced.
171 */
172 bool m_include_unsafe_inputs = false;
173 /** The version of the transaction we are trying to create. */
174 uint32_t m_version{CTransaction::CURRENT_VERSION};
175 /** The maximum weight for this transaction. */
176 std::optional<int> m_max_tx_weight{std::nullopt};
177 178 CoinSelectionParams(FastRandomContext& rng_fast, int change_output_size, int change_spend_size,
179 CAmount min_change_target, CFeeRate effective_feerate,
180 CFeeRate long_term_feerate, CFeeRate discard_feerate, int tx_noinputs_size, bool avoid_partial,
181 std::optional<int> max_tx_weight = std::nullopt)
182 : rng_fast{rng_fast},
183 change_output_size(change_output_size),
184 change_spend_size(change_spend_size),
185 m_min_change_target(min_change_target),
186 m_effective_feerate(effective_feerate),
187 m_long_term_feerate(long_term_feerate),
188 m_discard_feerate(discard_feerate),
189 tx_noinputs_size(tx_noinputs_size),
190 m_avoid_partial_spends(avoid_partial),
191 m_max_tx_weight(max_tx_weight)
192 {
193 }
194 CoinSelectionParams(FastRandomContext& rng_fast)
195 : rng_fast{rng_fast} {}
196 };
197 198 /** Parameters for filtering which OutputGroups we may use in coin selection.
199 * We start by being very selective and requiring multiple confirmations and
200 * then get more permissive if we cannot fund the transaction. */
201 struct CoinEligibilityFilter
202 {
203 /** Minimum number of confirmations for outputs that we sent to ourselves.
204 * We may use unconfirmed UTXOs sent from ourselves, e.g. change outputs. */
205 const int conf_mine;
206 /** Minimum number of confirmations for outputs received from a different wallet. */
207 const int conf_theirs;
208 /** Maximum number of unconfirmed ancestors aggregated across all UTXOs in an OutputGroup. */
209 const uint64_t max_ancestors;
210 /** Maximum cluster count that a single UTXO in the OutputGroup may have. In practice, this filter also caps the
211 * maximum descendant count, as a transaction's descendant count is never larger than its cluster count. */
212 const uint64_t max_cluster_count;
213 /** When avoid_reuse=true and there are full groups (OUTPUT_GROUP_MAX_ENTRIES), whether or not to use any partial groups.*/
214 const bool m_include_partial_groups{false};
215 216 CoinEligibilityFilter() = delete;
217 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) {}
218 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) {}
219 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) {}
220 221 bool operator<(const CoinEligibilityFilter& other) const {
222 return std::tie(conf_mine, conf_theirs, max_ancestors, max_cluster_count, m_include_partial_groups)
223 < std::tie(other.conf_mine, other.conf_theirs, other.max_ancestors, other.max_cluster_count, other.m_include_partial_groups);
224 }
225 };
226 227 /** A group of UTXOs paid to the same output script. */
228 struct OutputGroup
229 {
230 /** The list of UTXOs contained in this output group. */
231 std::vector<std::shared_ptr<COutput>> m_outputs;
232 /** Whether the UTXOs were sent by the wallet to itself. This is relevant because we may want at
233 * least a certain number of confirmations on UTXOs received from outside wallets while trusting
234 * our own UTXOs more. */
235 bool m_from_me{true};
236 /** The total value of the UTXOs in sum. */
237 CAmount m_value{0};
238 /** The minimum number of confirmations the UTXOs in the group have. Unconfirmed is 0. */
239 int m_depth{999};
240 /** The aggregated count of unconfirmed ancestors of all UTXOs in this
241 * group. Not deduplicated and may overestimate when ancestors are shared. */
242 size_t m_ancestors{0};
243 /** The maximum cluster count of a single UTXO in this output group. */
244 size_t m_max_cluster_count{0};
245 /** The value of the UTXOs after deducting the cost of spending them at the effective feerate. */
246 CAmount effective_value{0};
247 /** The fee to spend these UTXOs at the effective feerate. */
248 CAmount fee{0};
249 /** The fee to spend these UTXOs at the long term feerate. */
250 CAmount long_term_fee{0};
251 /** The feerate for spending a created change output eventually (i.e. not urgently, and thus at
252 * a lower feerate). Calculated using long term fee estimate. This is used to decide whether
253 * it could be economical to create a change output. */
254 CFeeRate m_long_term_feerate{0};
255 /** Indicate that we are subtracting the fee from outputs.
256 * When true, the value that is used for coin selection is the UTXO's real value rather than effective value */
257 bool m_subtract_fee_outputs{false};
258 /** Total weight of the UTXOs in this group. */
259 int m_weight{0};
260 261 OutputGroup() = default;
262 OutputGroup(const CoinSelectionParams& params) :
263 m_long_term_feerate(params.m_long_term_feerate),
264 m_subtract_fee_outputs(params.m_subtract_fee_outputs)
265 {}
266 267 void Insert(const std::shared_ptr<COutput>& output, size_t ancestors, size_t cluster_count);
268 bool EligibleForSpending(const CoinEligibilityFilter& eligibility_filter) const;
269 CAmount GetSelectionAmount() const;
270 };
271 272 struct Groups {
273 // Stores 'OutputGroup' containing only positive UTXOs (value > 0).
274 std::vector<OutputGroup> positive_group;
275 // Stores 'OutputGroup' which may contain both positive and negative UTXOs.
276 std::vector<OutputGroup> mixed_group;
277 };
278 279 /** Stores several 'Groups' whose were mapped by output type. */
280 struct OutputGroupTypeMap
281 {
282 // Maps output type to output groups.
283 std::map<OutputType, Groups> groups_by_type;
284 // All inserted groups, no type distinction.
285 Groups all_groups;
286 287 // Based on the insert flag; appends group to the 'mixed_group' and, if value > 0, to the 'positive_group'.
288 // This affects both; the groups filtered by type and the overall groups container.
289 void Push(const OutputGroup& group, OutputType type, bool insert_positive, bool insert_mixed);
290 // Different output types count
291 size_t TypesCount() { return groups_by_type.size(); }
292 };
293 294 typedef std::map<CoinEligibilityFilter, OutputGroupTypeMap> FilteredOutputGroups;
295 296 /** Choose a random change target for each transaction to make it harder to fingerprint the Core
297 * wallet based on the change output values of transactions it creates.
298 * Change target covers at least change fees and adds a random value on top of it.
299 * The random value is between 50ksat and min(2 * payment_value, 1milsat)
300 * When payment_value <= 25ksat, the value is just 50ksat.
301 *
302 * Making change amounts similar to the payment value may help disguise which output(s) are payments
303 * are which ones are change. Using double the payment value may increase the number of inputs
304 * needed (and thus be more expensive in fees), but breaks analysis techniques which assume the
305 * coins selected are just sufficient to cover the payment amount ("unnecessary input" heuristic).
306 *
307 * @param[in] payment_value Average payment value of the transaction output(s).
308 * @param[in] change_fee Fee for creating a change output.
309 */
310 [[nodiscard]] CAmount GenerateChangeTarget(CAmount payment_value, CAmount change_fee, FastRandomContext& rng);
311 312 enum class SelectionAlgorithm : uint8_t
313 {
314 BNB = 0,
315 KNAPSACK = 1,
316 SRD = 2,
317 CG = 3,
318 MANUAL = 4,
319 };
320 321 std::string GetAlgorithmName(SelectionAlgorithm algo);
322 323 struct OutputPtrComparator {
324 bool operator()(const std::shared_ptr<COutput>& a, const std::shared_ptr<COutput>& b) const {
325 return *a < *b;
326 }
327 };
328 using OutputSet = std::set<std::shared_ptr<COutput>, OutputPtrComparator>;
329 330 struct SelectionResult
331 {
332 private:
333 /** Set of inputs selected by the algorithm to use in the transaction */
334 OutputSet m_selected_inputs;
335 /** The target the algorithm selected for. Equal to the recipient amount plus non-input fees */
336 CAmount m_target;
337 /** The algorithm used to produce this result */
338 SelectionAlgorithm m_algo;
339 /** Whether the input values for calculations should be the effective value (true) or normal value (false) */
340 bool m_use_effective{false};
341 /** The computed waste */
342 std::optional<CAmount> m_waste;
343 /** False if algorithm was cut short by hitting limit of attempts and solution is non-optimal */
344 bool m_algo_completed{true};
345 /** The count of selections that were evaluated by this coin selection attempt */
346 size_t m_selections_evaluated;
347 /** Total weight of the selected inputs */
348 int m_weight{0};
349 /** How much individual inputs overestimated the bump fees for the shared ancestry */
350 CAmount bump_fee_group_discount{0};
351 352 template<typename T>
353 void InsertInputs(const T& inputs)
354 {
355 // Store sum of combined input sets to check that the results have no shared UTXOs
356 const size_t expected_count = m_selected_inputs.size() + inputs.size();
357 util::insert(m_selected_inputs, inputs);
358 if (m_selected_inputs.size() != expected_count) {
359 throw std::runtime_error(STR_INTERNAL_BUG("Shared UTXOs among selection results"));
360 }
361 }
362 363 public:
364 explicit SelectionResult(const CAmount target, SelectionAlgorithm algo)
365 : m_target(target), m_algo(algo) {}
366 367 SelectionResult() = delete;
368 369 /** Get the sum of the input values */
370 [[nodiscard]] CAmount GetSelectedValue() const;
371 372 [[nodiscard]] CAmount GetSelectedEffectiveValue() const;
373 374 [[nodiscard]] CAmount GetTotalBumpFees() const;
375 376 void Clear();
377 378 void AddInput(const OutputGroup& group);
379 void AddInputs(const OutputSet& inputs, bool subtract_fee_outputs);
380 381 /** How much individual inputs overestimated the bump fees for shared ancestries */
382 void SetBumpFeeDiscount(CAmount discount);
383 384 /** Calculates and stores the waste for this result given the cost of change
385 * and the opportunity cost of spending these inputs now vs in the future.
386 * If change exists, waste = change_cost + inputs * (effective_feerate - long_term_feerate) - bump_fee_group_discount
387 * If no change, waste = excess + inputs * (effective_feerate - long_term_feerate) - bump_fee_group_discount
388 * where excess = selected_effective_value - target
389 * change_cost = effective_feerate * change_output_size + long_term_feerate * change_spend_size
390 *
391 * @param[in] min_viable_change The minimum amount necessary to make a change output economic
392 * @param[in] change_cost The cost of creating a change output and spending it in the future. Only
393 * used if there is change, in which case it must be non-negative.
394 * @param[in] change_fee The fee for creating a change output
395 */
396 void RecalculateWaste(CAmount min_viable_change, CAmount change_cost, CAmount change_fee);
397 [[nodiscard]] CAmount GetWaste() const;
398 399 /** Tracks that algorithm was able to exhaustively search the entire combination space before hitting limit of tries */
400 void SetAlgoCompleted(bool algo_completed);
401 402 /** Get m_algo_completed */
403 bool GetAlgoCompleted() const;
404 405 /** Record the number of selections that were evaluated */
406 void SetSelectionsEvaluated(size_t attempts);
407 408 /** Get selections_evaluated */
409 size_t GetSelectionsEvaluated() const ;
410 411 /**
412 * Combines the @param[in] other selection result into 'this' selection result.
413 *
414 * Important note:
415 * There must be no shared 'COutput' among the two selection results being combined.
416 */
417 void Merge(const SelectionResult& other);
418 419 /** Get m_selected_inputs */
420 const OutputSet& GetInputSet() const;
421 /** Get the vector of COutputs that will be used to fill in a CTransaction's vin */
422 std::vector<std::shared_ptr<COutput>> GetShuffledInputVector() const;
423 424 bool operator<(SelectionResult other) const;
425 426 /** Get the amount for the change output after paying needed fees.
427 *
428 * The change amount is not 100% precise due to discrepancies in fee calculation.
429 * The final change amount (if any) should be corrected after calculating the final tx fees.
430 * When there is a discrepancy, most of the time the final change would be slightly bigger than estimated.
431 *
432 * Following are the possible factors of discrepancy:
433 * + non-input fees always include segwit flags
434 * + input fee estimation always include segwit stack size
435 * + input fees are rounded individually and not collectively, which leads to small rounding errors
436 * - input counter size is always assumed to be 1vbyte
437 *
438 * @param[in] min_viable_change Minimum amount for change output, if change would be less then we forgo change
439 * @param[in] change_fee Fees to include change output in the tx
440 * @returns Amount for change output, 0 when there is no change.
441 *
442 */
443 CAmount GetChange(CAmount min_viable_change, CAmount change_fee) const;
444 445 CAmount GetTarget() const { return m_target; }
446 447 SelectionAlgorithm GetAlgo() const { return m_algo; }
448 449 int GetWeight() const { return m_weight; }
450 };
451 452 util::Result<SelectionResult> SelectCoinsBnB(std::vector<OutputGroup>& utxo_pool, const CAmount& selection_target, const CAmount& cost_of_change,
453 int max_selection_weight);
454 455 util::Result<SelectionResult> CoinGrinder(std::vector<OutputGroup>& utxo_pool, const CAmount& selection_target, CAmount change_target, int max_selection_weight);
456 457 /** Select coins by Single Random Draw (SRD). SRD selects eligible OutputGroups from a shuffled
458 * ordering until the effective value of the input set suffices to create the recipient outputs and a
459 * change output with an amount of at least CHANGE_LOWER. While the maximum selection
460 * weight is exceeded during selection, the OutputGroup with the lowest effective value is dropped
461 * from the selection before additional OutputGroups are selected. Due to this greedy approach,
462 * SRD can fail to discover possible solutions in pathological cases.
463 *
464 * @param[in] utxo_pool The positive effective value OutputGroups eligible for selection
465 * @param[in] target_value The target value to select for
466 * @param[in] change_fee The cost of adding the change output to the transaction at the transaction’s feerate.
467 * @param[in] rng The randomness source to shuffle coins
468 * @param[in] max_selection_weight The maximum allowed weight for a selection result to be valid
469 * @returns If successful, a valid SelectionResult, otherwise, util::Error
470 */
471 util::Result<SelectionResult> SelectCoinsSRD(const std::vector<OutputGroup>& utxo_pool, CAmount target_value, CAmount change_fee, FastRandomContext& rng,
472 int max_selection_weight);
473 474 // Original coin selection algorithm as a fallback
475 util::Result<SelectionResult> KnapsackSolver(std::vector<OutputGroup>& groups, const CAmount& nTargetValue,
476 CAmount change_target, FastRandomContext& rng, int max_selection_weight);
477 } // namespace wallet
478 479 #endif // BITCOIN_WALLET_COINSELECTION_H
480