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/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 <vector>
20 : :
21 : : namespace node {
22 : : struct NodeContext;
23 : : } // namespace node
24 : :
25 : : class BlockValidationState;
26 : : class CScript;
27 : :
28 : : namespace interfaces {
29 : :
30 : : //! Block template interface
31 [ # # ]: 40615 : class BlockTemplate
32 : : {
33 : : public:
34 : 0 : virtual ~BlockTemplate() = default;
35 : :
36 : : virtual CBlockHeader getBlockHeader() = 0;
37 : : // Block contains a dummy coinbase transaction that should not be used.
38 : : virtual CBlock getBlock() = 0;
39 : :
40 : : // Fees per transaction, not including coinbase transaction.
41 : : virtual std::vector<CAmount> getTxFees() = 0;
42 : : // Sigop cost per transaction, not including coinbase transaction.
43 : : virtual std::vector<int64_t> getTxSigops() = 0;
44 : :
45 : : /**
46 : : * Return serialized dummy coinbase transaction.
47 : : *
48 : : * @note deprecated: use getCoinbaseTx()
49 : : */
50 : : virtual CTransactionRef getCoinbaseRawTx() = 0;
51 : :
52 : : /** Return fields needed to construct a coinbase transaction */
53 : : virtual node::CoinbaseTx getCoinbaseTx() = 0;
54 : :
55 : : /**
56 : : * Return scriptPubKey with SegWit OP_RETURN.
57 : : *
58 : : * @note deprecated: use getCoinbaseTx()
59 : : */
60 : : virtual std::vector<unsigned char> getCoinbaseCommitment() = 0;
61 : :
62 : : /**
63 : : * Return which output in the dummy coinbase contains the SegWit OP_RETURN.
64 : : *
65 : : * @note deprecated. Scan outputs from getCoinbaseTx() outputs field for the
66 : : * SegWit marker.
67 : : */
68 : : virtual int getWitnessCommitmentIndex() = 0;
69 : :
70 : : /**
71 : : * Compute merkle path to the coinbase transaction
72 : : *
73 : : * @return merkle path ordered from the deepest
74 : : */
75 : : virtual std::vector<uint256> getCoinbaseMerklePath() = 0;
76 : :
77 : : /**
78 : : * Construct and broadcast the block. Modifies the template in place,
79 : : * updating the fields listed below as well as the merkle root.
80 : : *
81 : : * @param[in] version version block header field
82 : : * @param[in] timestamp time block header field (unix timestamp)
83 : : * @param[in] nonce nonce block header field
84 : : * @param[in] coinbase complete coinbase transaction (including witness)
85 : : *
86 : : * @note unlike the submitblock RPC, this method does NOT add the
87 : : * coinbase witness automatically.
88 : : *
89 : : * @returns if the block was processed, does not necessarily indicate validity.
90 : : *
91 : : * @note Returns true if the block is already known, which can happen if
92 : : * the solved block is constructed and broadcast by multiple nodes
93 : : * (e.g. both the miner who constructed the template and the pool).
94 : : */
95 : : virtual bool submitSolution(uint32_t version, uint32_t timestamp, uint32_t nonce, CTransactionRef coinbase) = 0;
96 : :
97 : : /**
98 : : * Waits for fees in the next block to rise, a new tip or the timeout.
99 : : *
100 : : * @param[in] options Control the timeout (default forever) and by how much total fees
101 : : * for the next block should rise (default infinite).
102 : : *
103 : : * @returns a new BlockTemplate or nothing if the timeout occurs.
104 : : *
105 : : * On testnet this will additionally return a template with difficulty 1 if
106 : : * the tip is more than 20 minutes old.
107 : : */
108 : : virtual std::unique_ptr<BlockTemplate> waitNext(const node::BlockWaitOptions options = {}) = 0;
109 : :
110 : : /**
111 : : * Interrupts the current wait for the next block template.
112 : : */
113 : : virtual void interruptWait() = 0;
114 : : };
115 : :
116 : : //! Interface giving clients (RPC, Stratum v2 Template Provider in the future)
117 : : //! ability to create block templates.
118 [ # # ]: 1151 : class Mining
119 : : {
120 : : public:
121 : 0 : virtual ~Mining() = default;
122 : :
123 : : //! If this chain is exclusively used for testing
124 : : virtual bool isTestChain() = 0;
125 : :
126 : : //! Returns whether IBD is still in progress.
127 : : virtual bool isInitialBlockDownload() = 0;
128 : :
129 : : //! Returns the hash and height for the tip of this chain
130 : : virtual std::optional<BlockRef> getTip() = 0;
131 : :
132 : : /**
133 : : * Waits for the connected tip to change. During node initialization, this will
134 : : * wait until the tip is connected (regardless of `timeout`).
135 : : *
136 : : * @param[in] current_tip block hash of the current chain tip. Function waits
137 : : * for the chain tip to differ from this.
138 : : * @param[in] timeout how long to wait for a new tip (default is forever)
139 : : *
140 : : * @retval BlockRef hash and height of the current chain tip after this call.
141 : : * @retval std::nullopt if the node is shut down.
142 : : */
143 : : virtual std::optional<BlockRef> waitTipChanged(uint256 current_tip, MillisecondsDouble timeout = MillisecondsDouble::max()) = 0;
144 : :
145 : : /**
146 : : * Construct a new block template.
147 : : *
148 : : * During node initialization, this will wait until the tip is connected.
149 : : *
150 : : * @param[in] options options for creating the block
151 : : * @retval BlockTemplate a block template.
152 : : * @retval std::nullptr if the node is shut down.
153 : : */
154 : : virtual std::unique_ptr<BlockTemplate> createNewBlock(const node::BlockCreateOptions& options = {}) = 0;
155 : :
156 : : /**
157 : : * Checks if a given block is valid.
158 : : *
159 : : * @param[in] block the block to check
160 : : * @param[in] options verification options: the proof-of-work check can be
161 : : * skipped in order to verify a template generated by
162 : : * external software.
163 : : * @param[out] reason failure reason (BIP22)
164 : : * @param[out] debug more detailed rejection reason
165 : : * @returns whether the block is valid
166 : : *
167 : : * For signets the challenge verification is skipped when check_pow is false.
168 : : */
169 : : virtual bool checkBlock(const CBlock& block, const node::BlockCheckOptions& options, std::string& reason, std::string& debug) = 0;
170 : :
171 : : //! Get internal node context. Useful for RPC and testing,
172 : : //! but not accessible across processes.
173 : 0 : virtual node::NodeContext* context() { return nullptr; }
174 : : };
175 : :
176 : : //! Return implementation of Mining interface.
177 : : std::unique_ptr<Mining> MakeMining(node::NodeContext& node);
178 : :
179 : : } // namespace interfaces
180 : :
181 : : #endif // BITCOIN_INTERFACES_MINING_H
|
