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, 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        38471 : 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         1046 : 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.
      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
     100              :      * @returns               Hash and height of the current chain tip after this call.
     101              :      */
     102              :     virtual BlockRef waitTipChanged(uint256 current_tip, MillisecondsDouble timeout = MillisecondsDouble::max()) = 0;
     103              : 
     104              :    /**
     105              :      * Construct a new block template
     106              :      *
     107              :      * @param[in] options options for creating the block
     108              :      * @returns a block template
     109              :      */
     110              :     virtual std::unique_ptr<BlockTemplate> createNewBlock(const node::BlockCreateOptions& options = {}) = 0;
     111              : 
     112              :     //! Get internal node context. Useful for RPC and testing,
     113              :     //! but not accessible across processes.
     114            0 :     virtual node::NodeContext* context() { return nullptr; }
     115              : };
     116              : 
     117              : //! Return implementation of Mining interface.
     118              : std::unique_ptr<Mining> MakeMining(node::NodeContext& node);
     119              : 
     120              : } // namespace interfaces
     121              : 
     122              : #endif // BITCOIN_INTERFACES_MINING_H