Branch data Line data Source code
1 : : // Copyright (c) 2024 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> // for CAmount
9 : : #include <interfaces/types.h> // for BlockRef
10 : : #include <node/types.h> // for BlockCreateOptions
11 : : #include <primitives/block.h> // for CBlock, CBlockHeader
12 : : #include <primitives/transaction.h> // for CTransactionRef
13 : : #include <stdint.h> // for int64_t
14 : : #include <uint256.h> // for uint256
15 : : #include <util/time.h> // for MillisecondsDouble
16 : :
17 : : #include <memory> // for unique_ptr, shared_ptr
18 : : #include <optional> // for optional
19 : : #include <vector> // for 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 : : virtual CBlock getBlock() = 0;
38 : :
39 : : virtual std::vector<CAmount> getTxFees() = 0;
40 : : virtual std::vector<int64_t> getTxSigops() = 0;
41 : :
42 : : virtual CTransactionRef getCoinbaseTx() = 0;
43 : : virtual std::vector<unsigned char> getCoinbaseCommitment() = 0;
44 : : virtual int getWitnessCommitmentIndex() = 0;
45 : :
46 : : /**
47 : : * Compute merkle path to the coinbase transaction
48 : : *
49 : : * @return merkle path ordered from the deepest
50 : : */
51 : : virtual std::vector<uint256> getCoinbaseMerklePath() = 0;
52 : :
53 : : /**
54 : : * Construct and broadcast the block.
55 : : *
56 : : * @returns if the block was processed, independent of block validity
57 : : */
58 : : virtual bool submitSolution(uint32_t version, uint32_t timestamp, uint32_t nonce, CMutableTransaction coinbase) = 0;
59 : : };
60 : :
61 : : //! Interface giving clients (RPC, Stratum v2 Template Provider in the future)
62 : : //! ability to create block templates.
63 : 0 : class Mining
64 : : {
65 : : public:
66 : : virtual ~Mining() = default;
67 : :
68 : : //! If this chain is exclusively used for testing
69 : : virtual bool isTestChain() = 0;
70 : :
71 : : //! Returns whether IBD is still in progress.
72 : : virtual bool isInitialBlockDownload() = 0;
73 : :
74 : : //! Returns the hash and height for the tip of this chain
75 : : virtual std::optional<BlockRef> getTip() = 0;
76 : :
77 : : /**
78 : : * Waits for the connected tip to change. If the tip was not connected on
79 : : * startup, this will wait.
80 : : *
81 : : * @param[in] current_tip block hash of the current chain tip. Function waits
82 : : * for the chain tip to differ from this.
83 : : * @param[in] timeout how long to wait for a new tip
84 : : * @returns Hash and height of the current chain tip after this call.
85 : : */
86 : : virtual BlockRef waitTipChanged(uint256 current_tip, MillisecondsDouble timeout = MillisecondsDouble::max()) = 0;
87 : :
88 : : /**
89 : : * Construct a new block template
90 : : *
91 : : * @param[in] script_pub_key the coinbase output
92 : : * @param[in] options options for creating the block
93 : : * @returns a block template
94 : : */
95 : : virtual std::unique_ptr<BlockTemplate> createNewBlock(const CScript& script_pub_key, const node::BlockCreateOptions& options = {}) = 0;
96 : :
97 : : /**
98 : : * Processes new block. A valid new block is automatically relayed to peers.
99 : : *
100 : : * @param[in] block The block we want to process.
101 : : * @param[out] new_block A boolean which is set to indicate if the block was first received via this call
102 : : * @returns If the block was processed, independently of block validity
103 : : */
104 : : virtual bool processNewBlock(const std::shared_ptr<const CBlock>& block, bool* new_block) = 0;
105 : :
106 : : //! Return the number of transaction updates in the mempool,
107 : : //! used to decide whether to make a new block template.
108 : : virtual unsigned int getTransactionsUpdated() = 0;
109 : :
110 : : /**
111 : : * Check a block is completely valid from start to finish.
112 : : * Only works on top of our current best block.
113 : : * Does not check proof-of-work.
114 : : *
115 : : * @param[in] block the block to validate
116 : : * @param[in] check_merkle_root call CheckMerkleRoot()
117 : : * @param[out] state details of why a block failed to validate
118 : : * @returns false if it does not build on the current tip, or any of the checks fail
119 : : */
120 : : virtual bool testBlockValidity(const CBlock& block, bool check_merkle_root, BlockValidationState& state) = 0;
121 : :
122 : : //! Get internal node context. Useful for RPC and testing,
123 : : //! but not accessible across processes.
124 : 0 : virtual node::NodeContext* context() { return nullptr; }
125 : : };
126 : :
127 : : //! Return implementation of Mining interface.
128 : : std::unique_ptr<Mining> MakeMining(node::NodeContext& node);
129 : :
130 : : } // namespace interfaces
131 : :
132 : : #endif // BITCOIN_INTERFACES_MINING_H
|
