/bitcoin/src/wallet/spend.h
Line | Count | Source |
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, return only spendable outputs |
81 | | bool only_spendable{true}; |
82 | | // By default, do not include immature coinbase outputs |
83 | | bool include_immature_coinbase{false}; |
84 | | // By default, skip locked UTXOs |
85 | | bool skip_locked{true}; |
86 | | }; |
87 | | |
88 | | /** |
89 | | * Populate the CoinsResult struct with vectors of available COutputs, organized by OutputType. |
90 | | */ |
91 | | CoinsResult AvailableCoins(const CWallet& wallet, |
92 | | const CCoinControl* coinControl = nullptr, |
93 | | std::optional<CFeeRate> feerate = std::nullopt, |
94 | | const CoinFilterParams& params = {}) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet); |
95 | | |
96 | | /** |
97 | | * Wrapper function for AvailableCoins which skips the `feerate` and `CoinFilterParams::only_spendable` parameters. Use this function |
98 | | * to list all available coins (e.g. listunspent RPC) while not intending to fund a transaction. |
99 | | */ |
100 | | CoinsResult AvailableCoinsListUnspent(const CWallet& wallet, const CCoinControl* coinControl = nullptr, CoinFilterParams params = {}) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet); |
101 | | |
102 | | /** |
103 | | * Find non-change parent output. |
104 | | */ |
105 | | const CTxOut& FindNonChangeParentOutput(const CWallet& wallet, const COutPoint& outpoint) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet); |
106 | | |
107 | | /** |
108 | | * Return list of available coins and locked coins grouped by non-change output address. |
109 | | */ |
110 | | std::map<CTxDestination, std::vector<COutput>> ListCoins(const CWallet& wallet) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet); |
111 | | |
112 | | struct SelectionFilter { |
113 | | CoinEligibilityFilter filter; |
114 | | bool allow_mixed_output_types{true}; |
115 | | }; |
116 | | |
117 | | /** |
118 | | * Group coins by the provided filters. |
119 | | */ |
120 | | FilteredOutputGroups GroupOutputs(const CWallet& wallet, |
121 | | const CoinsResult& coins, |
122 | | const CoinSelectionParams& coin_sel_params, |
123 | | const std::vector<SelectionFilter>& filters); |
124 | | |
125 | | /** |
126 | | * Attempt to find a valid input set that preserves privacy by not mixing OutputTypes. |
127 | | * `ChooseSelectionResult()` will be called on each OutputType individually and the best |
128 | | * the solution (according to the waste metric) will be chosen. If a valid input cannot be found from any |
129 | | * single OutputType, fallback to running `ChooseSelectionResult()` over all available coins. |
130 | | * |
131 | | * param@[in] chain The chain interface to get information on unconfirmed UTXOs bump fees |
132 | | * param@[in] nTargetValue The target value |
133 | | * param@[in] groups The grouped outputs mapped by coin eligibility filters |
134 | | * param@[in] coin_selection_params Parameters for the coin selection |
135 | | * param@[in] allow_mixed_output_types Relax restriction that SelectionResults must be of the same OutputType |
136 | | * returns If successful, a SelectionResult containing the input set |
137 | | * If failed, returns (1) an empty error message if the target was not reached (general "Insufficient funds") |
138 | | * or (2) an specific error message if there was something particularly wrong (e.g. a selection |
139 | | * result that surpassed the tx max weight size). |
140 | | */ |
141 | | util::Result<SelectionResult> AttemptSelection(interfaces::Chain& chain, const CAmount& nTargetValue, OutputGroupTypeMap& groups, |
142 | | const CoinSelectionParams& coin_selection_params, bool allow_mixed_output_types); |
143 | | |
144 | | /** |
145 | | * Attempt to find a valid input set that meets the provided eligibility filter and target. |
146 | | * Multiple coin selection algorithms will be run and the input set that produces the least waste |
147 | | * (according to the waste metric) will be chosen. |
148 | | * |
149 | | * param@[in] chain The chain interface to get information on unconfirmed UTXOs bump fees |
150 | | * param@[in] nTargetValue The target value |
151 | | * param@[in] groups The struct containing the outputs grouped by script and divided by (1) positive only outputs and (2) all outputs (positive + negative). |
152 | | * param@[in] coin_selection_params Parameters for the coin selection |
153 | | * returns If successful, a SelectionResult containing the input set |
154 | | * If failed, returns (1) an empty error message if the target was not reached (general "Insufficient funds") |
155 | | * or (2) an specific error message if there was something particularly wrong (e.g. a selection |
156 | | * result that surpassed the tx max weight size). |
157 | | */ |
158 | | util::Result<SelectionResult> ChooseSelectionResult(interfaces::Chain& chain, const CAmount& nTargetValue, Groups& groups, const CoinSelectionParams& coin_selection_params); |
159 | | |
160 | | // User manually selected inputs that must be part of the transaction |
161 | | struct PreSelectedInputs |
162 | | { |
163 | | std::set<std::shared_ptr<COutput>> coins; |
164 | | // If subtract fee from outputs is disabled, the 'total_amount' |
165 | | // will be the sum of each output effective value |
166 | | // instead of the sum of the outputs amount |
167 | | CAmount total_amount{0}; |
168 | | |
169 | | void Insert(const COutput& output, bool subtract_fee_outputs) |
170 | 0 | { |
171 | 0 | if (subtract_fee_outputs) { Branch (171:13): [True: 0, False: 0]
|
172 | 0 | total_amount += output.txout.nValue; |
173 | 0 | } else { |
174 | 0 | total_amount += output.GetEffectiveValue(); |
175 | 0 | } |
176 | 0 | coins.insert(std::make_shared<COutput>(output)); |
177 | 0 | } |
178 | | }; |
179 | | |
180 | | /** |
181 | | * Fetch and validate coin control selected inputs. |
182 | | * Coins could be internal (from the wallet) or external. |
183 | | */ |
184 | | util::Result<PreSelectedInputs> FetchSelectedInputs(const CWallet& wallet, const CCoinControl& coin_control, |
185 | | const CoinSelectionParams& coin_selection_params) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet); |
186 | | |
187 | | /** |
188 | | * Select a set of coins such that nTargetValue is met; never select unconfirmed coins if they are not ours |
189 | | * param@[in] wallet The wallet which provides data necessary to spend the selected coins |
190 | | * param@[in] available_coins The struct of coins, organized by OutputType, available for selection prior to filtering |
191 | | * param@[in] nTargetValue The target value |
192 | | * param@[in] coin_selection_params Parameters for this coin selection such as feerates, whether to avoid partial spends, |
193 | | * and whether to subtract the fee from the outputs. |
194 | | * returns If successful, a SelectionResult containing the selected coins |
195 | | * If failed, returns (1) an empty error message if the target was not reached (general "Insufficient funds") |
196 | | * or (2) an specific error message if there was something particularly wrong (e.g. a selection |
197 | | * result that surpassed the tx max weight size). |
198 | | */ |
199 | | util::Result<SelectionResult> AutomaticCoinSelection(const CWallet& wallet, CoinsResult& available_coins, const CAmount& nTargetValue, |
200 | | const CoinSelectionParams& coin_selection_params) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet); |
201 | | |
202 | | /** |
203 | | * Select all coins from coin_control, and if coin_control 'm_allow_other_inputs=true', call 'AutomaticCoinSelection' to |
204 | | * select a set of coins such that nTargetValue - pre_set_inputs.total_amount is met. |
205 | | */ |
206 | | util::Result<SelectionResult> SelectCoins(const CWallet& wallet, CoinsResult& available_coins, const PreSelectedInputs& pre_set_inputs, |
207 | | const CAmount& nTargetValue, const CCoinControl& coin_control, |
208 | | const CoinSelectionParams& coin_selection_params) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet); |
209 | | |
210 | | struct CreatedTransactionResult |
211 | | { |
212 | | CTransactionRef tx; |
213 | | CAmount fee; |
214 | | FeeCalculation fee_calc; |
215 | | std::optional<unsigned int> change_pos; |
216 | | |
217 | | CreatedTransactionResult(CTransactionRef _tx, CAmount _fee, std::optional<unsigned int> _change_pos, const FeeCalculation& _fee_calc) |
218 | 0 | : tx(_tx), fee(_fee), fee_calc(_fee_calc), change_pos(_change_pos) {} |
219 | | }; |
220 | | |
221 | | /** |
222 | | * Create a new transaction paying the recipients with a set of coins |
223 | | * selected by SelectCoins(); Also create the change output, when needed |
224 | | * @note passing change_pos as std::nullopt will result in setting a random position |
225 | | */ |
226 | | util::Result<CreatedTransactionResult> CreateTransaction(CWallet& wallet, const std::vector<CRecipient>& vecSend, std::optional<unsigned int> change_pos, const CCoinControl& coin_control, bool sign = true); |
227 | | |
228 | | /** |
229 | | * Insert additional inputs into the transaction by |
230 | | * calling CreateTransaction(); |
231 | | */ |
232 | | util::Result<CreatedTransactionResult> FundTransaction(CWallet& wallet, const CMutableTransaction& tx, const std::vector<CRecipient>& recipients, std::optional<unsigned int> change_pos, bool lockUnspents, CCoinControl); |
233 | | } // namespace wallet |
234 | | |
235 | | #endif // BITCOIN_WALLET_SPEND_H |