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 <node/types.h>
       9                 :             : #include <uint256.h>
      10                 :             : 
      11                 :             : #include <memory>
      12                 :             : #include <optional>
      13                 :             : 
      14                 :             : namespace node {
      15                 :             : struct CBlockTemplate;
      16                 :             : struct NodeContext;
      17                 :             : } // namespace node
      18                 :             : 
      19                 :             : class BlockValidationState;
      20                 :             : class CBlock;
      21                 :             : class CScript;
      22                 :             : 
      23                 :             : namespace interfaces {
      24                 :             : 
      25                 :             : //! Interface giving clients (RPC, Stratum v2 Template Provider in the future)
      26                 :             : //! ability to create block templates.
      27                 :             : 
      28                 :           0 : class Mining
      29                 :             : {
      30                 :             : public:
      31                 :             :     virtual ~Mining() = default;
      32                 :             : 
      33                 :             :     //! If this chain is exclusively used for testing
      34                 :             :     virtual bool isTestChain() = 0;
      35                 :             : 
      36                 :             :     //! Returns whether IBD is still in progress.
      37                 :             :     virtual bool isInitialBlockDownload() = 0;
      38                 :             : 
      39                 :             :     //! Returns the hash for the tip of this chain
      40                 :             :     virtual std::optional<uint256> getTipHash() = 0;
      41                 :             : 
      42                 :             :    /**
      43                 :             :      * Construct a new block template
      44                 :             :      *
      45                 :             :      * @param[in] script_pub_key the coinbase output
      46                 :             :      * @param[in] options options for creating the block
      47                 :             :      * @returns a block template
      48                 :             :      */
      49                 :             :     virtual std::unique_ptr<node::CBlockTemplate> createNewBlock(const CScript& script_pub_key, const node::BlockCreateOptions& options={}) = 0;
      50                 :             : 
      51                 :             :     /**
      52                 :             :      * Processes new block. A valid new block is automatically relayed to peers.
      53                 :             :      *
      54                 :             :      * @param[in]   block The block we want to process.
      55                 :             :      * @param[out]  new_block A boolean which is set to indicate if the block was first received via this call
      56                 :             :      * @returns     If the block was processed, independently of block validity
      57                 :             :      */
      58                 :             :     virtual bool processNewBlock(const std::shared_ptr<const CBlock>& block, bool* new_block) = 0;
      59                 :             : 
      60                 :             :     //! Return the number of transaction updates in the mempool,
      61                 :             :     //! used to decide whether to make a new block template.
      62                 :             :     virtual unsigned int getTransactionsUpdated() = 0;
      63                 :             : 
      64                 :             :     /**
      65                 :             :      * Check a block is completely valid from start to finish.
      66                 :             :      * Only works on top of our current best block.
      67                 :             :      * Does not check proof-of-work.
      68                 :             :      *
      69                 :             :      * @param[in] block the block to validate
      70                 :             :      * @param[in] check_merkle_root call CheckMerkleRoot()
      71                 :             :      * @param[out] state details of why a block failed to validate
      72                 :             :      * @returns false if it does not build on the current tip, or any of the checks fail
      73                 :             :      */
      74                 :             :     virtual bool testBlockValidity(const CBlock& block, bool check_merkle_root, BlockValidationState& state) = 0;
      75                 :             : 
      76                 :             :     //! Get internal node context. Useful for RPC and testing,
      77                 :             :     //! but not accessible across processes.
      78                 :           0 :     virtual node::NodeContext* context() { return nullptr; }
      79                 :             : };
      80                 :             : 
      81                 :             : //! Return implementation of Mining interface.
      82                 :             : std::unique_ptr<Mining> MakeMining(node::NodeContext& node);
      83                 :             : 
      84                 :             : } // namespace interfaces
      85                 :             : 
      86                 :             : #endif // BITCOIN_INTERFACES_MINING_H