1 // Copyright (c) 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 //! @file node/mining_types.h is used externally by mining IPC clients, so it should
6 //! only declare simple data definitions.
7 //!
8 //! Avoid declaring functions or classes with methods here unless they are
9 //! header-only or provided by the util library.
10 11 #ifndef BITCOIN_NODE_MINING_TYPES_H
12 #define BITCOIN_NODE_MINING_TYPES_H
13 14 #include <consensus/amount.h>
15 #include <policy/feerate.h>
16 #include <policy/policy.h>
17 #include <primitives/transaction.h>
18 #include <script/script.h>
19 #include <uint256.h>
20 #include <util/time.h>
21 22 #include <cstddef>
23 #include <cstdint>
24 #include <optional>
25 #include <vector>
26 27 namespace node {
28 29 /**
30 * Block template creation options. These override node defaults, but can't
31 * exceed node limits (e.g. block_reserved_weight can't exceed max block weight).
32 */
33 struct BlockCreateOptions {
34 /**
35 * Set false to omit mempool transactions
36 */
37 bool use_mempool{true};
38 /**
39 * Minimum fee rate for transactions to be included. Providing a value
40 * overrides the -blockmintxfee startup setting.
41 */
42 std::optional<CFeeRate> block_min_fee_rate{};
43 /**
44 * Whether to log the fee rate of each transaction when it is added to the
45 * block template. Providing a value overrides the -printpriority startup
46 * setting.
47 */
48 std::optional<bool> print_modified_fee{};
49 /**
50 * The default reserved weight for the fixed-size block header,
51 * transaction count and coinbase transaction. Minimum: 2000 weight units
52 * (MINIMUM_BLOCK_RESERVED_WEIGHT).
53 *
54 * Providing a value overrides the `-blockreservedweight` startup setting.
55 * Cap'n Proto IPC clients currently cannot leave this field unset, so they
56 * always provide a value.
57 */
58 std::optional<uint64_t> block_reserved_weight{};
59 /**
60 * Maximum block weight, defaults to -maxblockweight
61 *
62 * Must not be lower than block_reserved_weight. Setting this equal to
63 * block_reserved_weight leaves no room for non-coinbase transactions.
64 */
65 std::optional<uint64_t> block_max_weight{};
66 /**
67 * The maximum additional sigops which the pool will add in coinbase
68 * transaction outputs.
69 */
70 size_t coinbase_output_max_additional_sigops{DEFAULT_COINBASE_OUTPUT_MAX_ADDITIONAL_SIGOPS};
71 /**
72 * Script to put in the coinbase transaction. The default is an
73 * anyone-can-spend dummy.
74 *
75 * Should only be used for tests, when the default doesn't suffice.
76 *
77 * Note that higher level code like the getblocktemplate RPC may omit the
78 * coinbase transaction entirely. It's instead constructed by pool software
79 * using fields like coinbasevalue, coinbaseaux and default_witness_commitment.
80 * This software typically also controls the payout outputs, even for solo
81 * mining.
82 *
83 * The size and sigops are not checked against
84 * coinbase_max_additional_weight and coinbase_output_max_additional_sigops.
85 */
86 CScript coinbase_output_script{CScript() << OP_TRUE};
87 /**
88 * Whether to call TestBlockValidity() at the end of CreateNewBlock().
89 * Should only be disabled for tests / benchmarks.
90 */
91 bool test_block_validity{true};
92 };
93 94 struct BlockWaitOptions {
95 /**
96 * How long to wait before returning nullptr instead of a new template.
97 * Default is to wait forever.
98 */
99 MillisecondsDouble timeout{MillisecondsDouble::max()};
100 101 /**
102 * The wait method will not return a new template unless it has fees at
103 * least fee_threshold sats higher than the current template, or unless
104 * the chain tip changes and the previous template is no longer valid.
105 *
106 * A caller may not be interested in templates with higher fees, and
107 * determining whether fee_threshold is reached is also expensive. So as
108 * an optimization, when fee_threshold is set to MAX_MONEY (default), the
109 * implementation is able to be much more efficient, skipping expensive
110 * checks and only returning new templates when the chain tip changes.
111 */
112 CAmount fee_threshold{MAX_MONEY};
113 };
114 115 struct BlockCheckOptions {
116 /**
117 * Set false to omit the merkle root check
118 */
119 bool check_merkle_root{true};
120 121 /**
122 * Set false to omit the proof-of-work check
123 */
124 bool check_pow{true};
125 };
126 127 /**
128 * Template containing all coinbase transaction fields that are set by our
129 * miner code. Clients are expected to add their own outputs and typically
130 * also expand the scriptSig.
131 */
132 struct CoinbaseTx {
133 /* nVersion */
134 uint32_t version;
135 /* nSequence for the only coinbase transaction input */
136 uint32_t sequence;
137 /**
138 * Prefix which needs to be placed at the beginning of the scriptSig.
139 * Clients may append extra data to this as long as the overall scriptSig
140 * size is 100 bytes or less, to avoid the block being rejected with
141 * "bad-cb-length" error. At heights <= 16 the BIP 34 height push is only
142 * one byte long, so clients must append at least one additional byte to
143 * meet the consensus minimum scriptSig length of two bytes.
144 *
145 * Currently with BIP 34, the prefix is guaranteed to be less than 8 bytes,
146 * but future soft forks could require longer prefixes.
147 */
148 CScript script_sig_prefix;
149 /**
150 * The first (and only) witness stack element of the coinbase input.
151 *
152 * Omitted for block templates without witness data.
153 *
154 * This is currently the BIP 141 witness reserved value, and can be chosen
155 * arbitrarily by the node, but future soft forks may constrain it.
156 */
157 std::optional<uint256> witness;
158 /**
159 * Block subsidy plus fees, minus any non-zero required_outputs.
160 *
161 * Currently there are no non-zero required_outputs, so block_reward_remaining
162 * is the entire block reward. See also required_outputs.
163 */
164 CAmount block_reward_remaining;
165 /*
166 * To be included as the last outputs in the coinbase transaction.
167 * Currently this is only the witness commitment OP_RETURN, but future
168 * softforks or a custom mining patch could add more.
169 *
170 * The dummy output that spends the full reward is excluded.
171 */
172 std::vector<CTxOut> required_outputs;
173 uint32_t lock_time;
174 };
175 176 } // namespace node
177 178 #endif // BITCOIN_NODE_MINING_TYPES_H
179