Inside Bitcoin

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
27namespace 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 */
33struct 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
94struct 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
115struct 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 */
132struct 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