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 325505 : 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 add the
64 : * coinbase witness automatically.
65 : *
66 : * @note for heights <= 16, the BIP34 height push in getCoinbaseTx().script_sig_prefix
67 : * is only one byte long, so the coinbase scriptSig needs at least
68 : * one additional byte of data to avoid bad-cb-length.
69 : *
70 : * @returns if the block was processed, does not necessarily indicate validity.
71 : *
72 : * @note Returns true if the block is already known, which can happen if
73 : * the solved block is constructed and broadcast by multiple nodes
74 : * (e.g. both the miner who constructed the template and the pool).
75 : */
76 : virtual bool submitSolution(uint32_t version, uint32_t timestamp, uint32_t nonce, CTransactionRef coinbase) = 0;
77 :
78 : /**
79 : * Waits for fees in the next block to rise, a new tip or the timeout.
80 : *
81 : * @param[in] options Control the timeout (default forever) and by how much total fees
82 : * for the next block should rise (default infinite).
83 : *
84 : * @returns a new BlockTemplate or nothing if the timeout occurs.
85 : *
86 : * On testnet this will additionally return a template with difficulty 1 if
87 : * the tip is more than 20 minutes old.
88 : */
89 : virtual std::unique_ptr<BlockTemplate> waitNext(node::BlockWaitOptions options = {}) = 0;
90 :
91 : /**
92 : * Interrupts the current wait for the next block template.
93 : */
94 : virtual void interruptWait() = 0;
95 : };
96 :
97 : //! Interface giving clients (RPC, Stratum v2 Template Provider in the future)
98 : //! ability to create block templates.
99 325505 : class Mining
100 : {
101 : public:
102 : virtual ~Mining() = default;
103 :
104 : //! If this chain is exclusively used for testing
105 : virtual bool isTestChain() = 0;
106 :
107 : //! Returns whether IBD is still in progress.
108 : virtual bool isInitialBlockDownload() = 0;
109 :
110 : //! Returns the hash and height for the tip of this chain
111 : virtual std::optional<BlockRef> getTip() = 0;
112 :
113 : /**
114 : * Waits for the connected tip to change. During node initialization, this will
115 : * wait until the tip is connected (regardless of `timeout`).
116 : *
117 : * @param[in] current_tip block hash of the current chain tip. Function waits
118 : * for the chain tip to differ from this.
119 : * @param[in] timeout how long to wait for a new tip (default is forever)
120 : *
121 : * @retval BlockRef hash and height of the current chain tip after this call.
122 : * @retval std::nullopt if the node is shut down or interrupt() is called.
123 : */
124 : virtual std::optional<BlockRef> waitTipChanged(uint256 current_tip, MillisecondsDouble timeout = MillisecondsDouble::max()) = 0;
125 :
126 : /**
127 : * Construct a new block template.
128 : *
129 : * @param[in] options options for creating the block
130 : * @param[in] cooldown wait for tip to be connected and IBD to complete.
131 : * If the best header is ahead of the tip, wait for the
132 : * tip to catch up. It's recommended to disable this on
133 : * regtest and signets with only one miner, as these
134 : * could stall.
135 : * @retval BlockTemplate a block template.
136 : * @retval std::nullptr if the node is shut down or interrupt() is called.
137 : */
138 : virtual std::unique_ptr<BlockTemplate> createNewBlock(const node::BlockCreateOptions& options = {}, bool cooldown = true) = 0;
139 :
140 : /**
141 : * Interrupts createNewBlock and waitTipChanged.
142 : */
143 : virtual void interrupt() = 0;
144 :
145 : /**
146 : * Checks if a given block is valid.
147 : *
148 : * @param[in] block the block to check
149 : * @param[in] options verification options: the proof-of-work check can be
150 : * skipped in order to verify a template generated by
151 : * external software.
152 : * @param[out] reason failure reason (BIP22)
153 : * @param[out] debug more detailed rejection reason
154 : * @returns whether the block is valid
155 : *
156 : * For signets the challenge verification is skipped when check_pow is false.
157 : */
158 : virtual bool checkBlock(const CBlock& block, const node::BlockCheckOptions& options, std::string& reason, std::string& debug) = 0;
159 :
160 : //! Get internal node context. Useful for RPC and testing,
161 : //! but not accessible across processes.
162 0 : virtual const node::NodeContext* context() { return nullptr; }
163 : };
164 :
165 : //! Return implementation of Mining interface.
166 : //!
167 : //! @param[in] wait_loaded waits for chainstate data to be loaded before
168 : //! returning. Used to prevent external clients from
169 : //! being able to crash the node during startup.
170 : std::unique_ptr<Mining> MakeMining(const node::NodeContext& node, bool wait_loaded=true);
171 :
172 : } // namespace interfaces
173 :
174 : #endif // BITCOIN_INTERFACES_MINING_H
|
