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 class BlockTemplate
30 {
31 public:
32 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 class Mining
102 {
103 public:
104 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 /**
184 * Fetch raw transactions from the mempool by txid.
185 *
186 * @param[in] txids transaction ids to look up
187 * @returns one entry per requested txid containing the
188 * transaction if found, otherwise nullptr
189 */
190 virtual std::vector<CTransactionRef> getTransactionsByTxID(const std::vector<Txid>& txids) = 0;
191 192 /**
193 * Fetch raw transactions from the mempool by wtxid.
194 *
195 * @param[in] wtxids witness transaction ids to look up
196 * @returns one entry per requested wtxid containing the
197 * transaction if found, otherwise nullptr
198 */
199 virtual std::vector<CTransactionRef> getTransactionsByWitnessID(const std::vector<Wtxid>& wtxids) = 0;
200 201 //! Get internal node context. Useful for RPC and testing,
202 //! but not accessible across processes.
203 virtual const node::NodeContext* context() { return nullptr; }
204 };
205 206 //! Return implementation of Mining interface.
207 //!
208 //! @param[in] wait_loaded waits for chainstate data to be loaded before
209 //! returning. Used to prevent external clients from
210 //! being able to crash the node during startup.
211 std::unique_ptr<Mining> MakeMining(const node::NodeContext& node, bool wait_loaded=true);
212 213 } // namespace interfaces
214 215 #endif // BITCOIN_INTERFACES_MINING_H
216