Branch data Line data Source code
1 : : // Copyright (c) 2024-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_INTERFACES_MINING_H
6 : : #define BITCOIN_INTERFACES_MINING_H
7 : :
8 : : #include <consensus/amount.h>
9 : : #include <interfaces/types.h>
10 : : #include <node/mining_types.h>
11 : : #include <primitives/block.h>
12 : : #include <primitives/transaction.h>
13 : : #include <uint256.h>
14 : : #include <util/time.h>
15 : :
16 : : #include <cstdint>
17 : : #include <memory>
18 : : #include <optional>
19 : : #include <string>
20 : : #include <vector>
21 : :
22 : : namespace node {
23 : : struct NodeContext;
24 : : } // namespace node
25 : :
26 : : namespace interfaces {
27 : :
28 : : //! Block template interface
29 [ # # ]: 49518 : class BlockTemplate
30 : : {
31 : : public:
32 : 0 : virtual ~BlockTemplate() = default;
33 : :
34 : : virtual CBlockHeader getBlockHeader() = 0;
35 : : // Block contains a dummy coinbase transaction that should not be used and
36 : : // it may not match a transaction constructed from getCoinbaseTx().
37 : : virtual CBlock getBlock() = 0;
38 : :
39 : : // Fees per transaction, not including coinbase transaction.
40 : : virtual std::vector<CAmount> getTxFees() = 0;
41 : : // Sigop cost per transaction, not including coinbase transaction.
42 : : virtual std::vector<int64_t> getTxSigops() = 0;
43 : :
44 : : /** Return fields needed to construct a coinbase transaction */
45 : : virtual node::CoinbaseTx getCoinbaseTx() = 0;
46 : :
47 : : /**
48 : : * Compute merkle path to the coinbase transaction
49 : : *
50 : : * @return merkle path ordered from the deepest
51 : : */
52 : : virtual std::vector<uint256> getCoinbaseMerklePath() = 0;
53 : :
54 : : /**
55 : : * Construct and broadcast the block. Modifies the template in place,
56 : : * updating the fields listed below as well as the merkle root.
57 : : *
58 : : * @param[in] version version block header field
59 : : * @param[in] timestamp time block header field (unix timestamp)
60 : : * @param[in] nonce nonce block header field
61 : : * @param[in] coinbase complete coinbase transaction (including witness)
62 : : *
63 : : * @note Unlike the submitblock RPC, this method does not call
64 : : * UpdateUncommittedBlockStructures to add a missing coinbase witness
65 : : * reserved value. Callers must provide a complete coinbase transaction,
66 : : * including the witness when a witness commitment is present.
67 : : *
68 : : * @note for heights <= 16, the BIP34 height push in getCoinbaseTx().script_sig_prefix
69 : : * is only one byte long, so the coinbase scriptSig needs at least
70 : : * one additional byte of data to avoid bad-cb-length.
71 : : *
72 : : * @returns if the block was processed, does not necessarily indicate validity.
73 : : *
74 : : * @note Returns true if the block is already known, which can happen if
75 : : * the solved block is constructed and broadcast by multiple nodes
76 : : * (e.g. both the miner who constructed the template and the pool).
77 : : */
78 : : virtual bool submitSolution(uint32_t version, uint32_t timestamp, uint32_t nonce, CTransactionRef coinbase) = 0;
79 : :
80 : : /**
81 : : * Waits for fees in the next block to rise, a new tip or the timeout.
82 : : *
83 : : * @param[in] options Control the timeout (default forever) and by how much total fees
84 : : * for the next block should rise (default infinite).
85 : : *
86 : : * @returns a new BlockTemplate or nothing if the timeout occurs.
87 : : *
88 : : * On testnet this will additionally return a template with difficulty 1 if
89 : : * the tip is more than 20 minutes old.
90 : : */
91 : : virtual std::unique_ptr<BlockTemplate> waitNext(node::BlockWaitOptions options = {}) = 0;
92 : :
93 : : /**
94 : : * Interrupts the current wait for the next block template.
95 : : */
96 : : virtual void interruptWait() = 0;
97 : : };
98 : :
99 : : //! Interface giving clients (RPC, Stratum v2 Template Provider in the future)
100 : : //! ability to create block templates.
101 [ # # ]: 9495 : class Mining
102 : : {
103 : : public:
104 : 0 : virtual ~Mining() = default;
105 : :
106 : : //! If this chain is exclusively used for testing
107 : : virtual bool isTestChain() = 0;
108 : :
109 : : //! Returns whether IBD is still in progress.
110 : : virtual bool isInitialBlockDownload() = 0;
111 : :
112 : : //! Returns the hash and height for the tip of this chain
113 : : virtual std::optional<BlockRef> getTip() = 0;
114 : :
115 : : /**
116 : : * Waits for the connected tip to change. During node initialization, this will
117 : : * wait until the tip is connected (regardless of `timeout`).
118 : : *
119 : : * @param[in] current_tip block hash of the current chain tip. Function waits
120 : : * for the chain tip to differ from this.
121 : : * @param[in] timeout how long to wait for a new tip (default is forever)
122 : : *
123 : : * @retval BlockRef hash and height of the current chain tip after this call.
124 : : * @retval std::nullopt if the node is shut down or interrupt() is called.
125 : : */
126 : : virtual std::optional<BlockRef> waitTipChanged(uint256 current_tip, MillisecondsDouble timeout = MillisecondsDouble::max()) = 0;
127 : :
128 : : /**
129 : : * Construct a new block template.
130 : : *
131 : : * @param[in] options options for creating the block
132 : : * @param[in] cooldown wait for tip to be connected and IBD to complete.
133 : : * If the best header is ahead of the tip, wait for the
134 : : * tip to catch up. It's recommended to disable this on
135 : : * regtest and signets with only one miner, as these
136 : : * could stall.
137 : : * @retval BlockTemplate a block template.
138 : : * @retval std::nullptr if the node is shut down or interrupt() is called.
139 : : */
140 : : virtual std::unique_ptr<BlockTemplate> createNewBlock(const node::BlockCreateOptions& options = {}, bool cooldown = true) = 0;
141 : :
142 : : /**
143 : : * Interrupts createNewBlock and waitTipChanged.
144 : : */
145 : : virtual void interrupt() = 0;
146 : :
147 : : /**
148 : : * Checks if a given block is valid.
149 : : *
150 : : * @param[in] block the block to check
151 : : * @param[in] options verification options: the proof-of-work check can be
152 : : * skipped in order to verify a template generated by
153 : : * external software.
154 : : * @param[out] reason failure reason (BIP22)
155 : : * @param[out] debug more detailed rejection reason
156 : : * @returns whether the block is valid
157 : : *
158 : : * For signets the challenge verification is skipped when check_pow is false.
159 : : */
160 : : virtual bool checkBlock(const CBlock& block, const node::BlockCheckOptions& options, std::string& reason, std::string& debug) = 0;
161 : :
162 : : /**
163 : : * Process a fully assembled block.
164 : : *
165 : : * Similar to the submitblock RPC. Accepts a complete block, validates
166 : : * it, and if accepted as new, processes it into chainstate. Accepted
167 : : * blocks may then be announced to peers through normal validation signals.
168 : : *
169 : : * @param[in] block the complete block to submit
170 : : * @param[out] reason failure reason (BIP22)
171 : : * @param[out] debug more detailed rejection reason
172 : : * @returns true if the block was accepted as a new block. Returns
173 : : * false and sets reason if the block is a duplicate or
174 : : * the validation result is inconclusive.
175 : : *
176 : : * @note Unlike the submitblock RPC, this method does not call
177 : : * UpdateUncommittedBlockStructures to add a missing coinbase witness
178 : : * reserved value. Callers must submit a fully formed block, including
179 : : * the coinbase witness when a witness commitment is present.
180 : : */
181 : : virtual bool submitBlock(const CBlock& block, std::string& reason, std::string& debug) = 0;
182 : :
183 : : //! Get internal node context. Useful for RPC and testing,
184 : : //! but not accessible across processes.
185 : 0 : virtual const node::NodeContext* context() { return nullptr; }
186 : : };
187 : :
188 : : //! Return implementation of Mining interface.
189 : : //!
190 : : //! @param[in] wait_loaded waits for chainstate data to be loaded before
191 : : //! returning. Used to prevent external clients from
192 : : //! being able to crash the node during startup.
193 : : std::unique_ptr<Mining> MakeMining(const node::NodeContext& node, bool wait_loaded=true);
194 : :
195 : : } // namespace interfaces
196 : :
197 : : #endif // BITCOIN_INTERFACES_MINING_H
|
