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      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  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      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