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