Repository: bitcoin/bitcoin
File: src/interfaces/mining.h (C/C++)

Code before:

namespace interfaces {

//! Block template interface
class BlockTemplate
{
public:
    virtual ~BlockTemplate() = default;

    virtual CBlockHeader getBlockHeader() = 0;
    virtual CBlock getBlock() = 0;

    virtual std::vector<CAmount> getTxFees() = 0;
    virtual std::vector<int64_t> getTxSigops() = 0;

    virtual CTransactionRef getCoinbaseTx() = 0;
    virtual std::vector<unsigned char> getCoinbaseCommitment() = 0;
    virtual int getWitnessCommitmentIndex() = 0;
};

//! Interface giving clients (RPC, Stratum v2 Template Provider in the future)
//! ability to create block templates.
class Mining
{
public:
    virtual ~Mining() = default;

    //! If this chain is exclusively used for testing
    virtual bool isTestChain() = 0;

    //! Returns whether IBD is still in progress.
    virtual bool isInitialBlockDownload() = 0;

    //! Returns the hash for the tip of this chain
    virtual std::optional<uint256> getTipHash() = 0;

    /**
     * Construct a new block template
     *
     * @param[in] script_pub_key the coinbase output
     * @param[in] options options for creating the block
     * @returns a block template
     */
    virtual std::unique_ptr<BlockTemplate> createNewBlock(const CScript& script_pub_key, const node::BlockCreateOptions& options = {}) = 0;

    /**
     * Processes new block. A valid new block is automatically relayed to peers.
     *
     * @param[in]   block The block we want to process.
     * @param[out]  new_block A boolean which is set to indicate if the block was first received via this call
     * @returns     If the block was processed, independently of block validity

Review comment (suggestion):
In commit "Add waitTipChanged to Mining interface" (4554b3b1adf678e17d479d72738f4f2089971c4a)

Not important, but it could be good to return [`BlockKey`](https://github.com/bitcoin/bitcoin/blob/5d280130446d57d653c749005a2e363265d87686/src/interfaces/chain.h#L44-L48) struct here instead of std::pair. Could also be good to provide a more consistent interface instead of separate getTipHash() and getTipHeight() functions:

```c++
virtual BlockKey getTip() = 0;
virtual BlockKey waitTipChanged(MillisecondsDouble timeout = MillisecondsDouble::max()) = 0;
```

If you do use `BlockKey` here would suggest moving it from `interfaces/chain.h` to `interfaces/types.h`. Also I think I a name like `BlockId` or `BlockRef` would be better than `BlockKey` in this context, given other implications ofthe word "key". But feel free to move/rename/reuse BlockKey from chain.h here, or not.

Code after:
class BlockValidationState;
class CScript;

namespace interfaces {

//! Block template interface
class BlockTemplate
{
public:
    virtual ~BlockTemplate() = default;

    virtual CBlockHeader getBlockHeader() = 0;
    virtual CBlock getBlock() = 0;

    virtual std::vector<CAmount> getTxFees() = 0;
    virtual std::vector<int64_t> getTxSigops() = 0;

    virtual CTransactionRef getCoinbaseTx() = 0;
    virtual std::vector<unsigned char> getCoinbaseCommitment() = 0;
    virtual int getWitnessCommitmentIndex() = 0;
};

//! Interface giving clients (RPC, Stratum v2 Template Provider in the future)
//! ability to create block templates.
class Mining
{
public:
    virtual ~Mining() = default;

    //! If this chain is exclusively used for testing
    virtual bool isTestChain() = 0;

    //! Returns whether IBD is still in progress.
    virtual bool isInitialBlockDownload() = 0;

    //! Returns the hash and height for the tip of this chain
    virtual std::optional<BlockRef> getTip() = 0;

    /**
     * Waits for the tip to change
     *
     * @param[in] current_tip block hash of the current chain tip. Function waits
     *                        for the chain tip to change if this matches, otherwise
     *                        it returns right away.
     * @param[in] timeout     how long to wait for a new tip
     * @returns               Hash and height of the current chain tip after this call.
     */
    virtual BlockRef waitTipChanged(uint256 current_tip, MillisecondsDouble timeout = MillisecondsDouble::max()) = 0;

   /**
     * Construct a new block template