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