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         [ -  + ]:       38066 : 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, CTransactionRef coinbase) = 0;
      59                 :             : };
      60                 :             : 
      61                 :             : //! Interface giving clients (RPC, Stratum v2 Template Provider in the future)
      62                 :             : //! ability to create block templates.
      63                 :        1020 : 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. During node initialization, this will
      79                 :             :      * wait until the tip is connected.
      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] options options for creating the block
      92                 :             :      * @returns a block template
      93                 :             :      */
      94                 :             :     virtual std::unique_ptr<BlockTemplate> createNewBlock(const node::BlockCreateOptions& options = {}) = 0;
      95                 :             : 
      96                 :             :     //! Get internal node context. Useful for RPC and testing,
      97                 :             :     //! but not accessible across processes.
      98                 :           0 :     virtual node::NodeContext* context() { return nullptr; }
      99                 :             : };
     100                 :             : 
     101                 :             : //! Return implementation of Mining interface.
     102                 :             : std::unique_ptr<Mining> MakeMining(node::NodeContext& node);
     103                 :             : 
     104                 :             : } // namespace interfaces
     105                 :             : 
     106                 :             : #endif // BITCOIN_INTERFACES_MINING_H