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, BlockWaitOptions
 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  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.
 58       *
 59       * @returns if the block was processed, independent of block validity
 60       */
 61      virtual bool submitSolution(uint32_t version, uint32_t timestamp, uint32_t nonce, CTransactionRef coinbase) = 0;
 62  
 63      /**
 64       * Waits for fees in the next block to rise, a new tip or the timeout.
 65       *
 66       * @param[in] options   Control the timeout (default forever) and by how much total fees
 67       *                      for the next block should rise (default infinite).
 68       *
 69       * @returns a new BlockTemplate or nothing if the timeout occurs.
 70       *
 71       * On testnet this will additionally return a template with difficulty 1 if
 72       * the tip is more than 20 minutes old.
 73       */
 74      virtual std::unique_ptr<BlockTemplate> waitNext(const node::BlockWaitOptions options = {}) = 0;
 75  };
 76  
 77  //! Interface giving clients (RPC, Stratum v2 Template Provider in the future)
 78  //! ability to create block templates.
 79  class Mining
 80  {
 81  public:
 82      virtual ~Mining() = default;
 83  
 84      //! If this chain is exclusively used for testing
 85      virtual bool isTestChain() = 0;
 86  
 87      //! Returns whether IBD is still in progress.
 88      virtual bool isInitialBlockDownload() = 0;
 89  
 90      //! Returns the hash and height for the tip of this chain
 91      virtual std::optional<BlockRef> getTip() = 0;
 92  
 93      /**
 94       * Waits for the connected tip to change. During node initialization, this will
 95       * wait until the tip is connected (regardless of `timeout`).
 96       *
 97       * @param[in] current_tip block hash of the current chain tip. Function waits
 98       *                        for the chain tip to differ from this.
 99       * @param[in] timeout     how long to wait for a new tip (default is forever)
100       *
101       * @retval BlockRef hash and height of the current chain tip after this call.
102       * @retval std::nullopt if the node is shut down.
103       */
104      virtual std::optional<BlockRef> waitTipChanged(uint256 current_tip, MillisecondsDouble timeout = MillisecondsDouble::max()) = 0;
105  
106     /**
107       * Construct a new block template.
108       *
109       * During node initialization, this will wait until the tip is connected.
110       *
111       * @param[in] options options for creating the block
112       * @retval BlockTemplate a block template.
113       * @retval std::nullptr if the node is shut down.
114       */
115      virtual std::unique_ptr<BlockTemplate> createNewBlock(const node::BlockCreateOptions& options = {}) = 0;
116  
117      //! Get internal node context. Useful for RPC and testing,
118      //! but not accessible across processes.
119      virtual node::NodeContext* context() { return nullptr; }
120  };
121  
122  //! Return implementation of Mining interface.
123  std::unique_ptr<Mining> MakeMining(node::NodeContext& node);
124  
125  } // namespace interfaces
126  
127  #endif // BITCOIN_INTERFACES_MINING_H