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

Code before:
// Copyright (c) 2024 The Bitcoin Core developers
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.

#ifndef BITCOIN_INTERFACES_MINING_H
#define BITCOIN_INTERFACES_MINING_H

namespace node {
struct NodeContext;
} // namespace node

class BlockValidationState;
class CBlock;

namespace interfaces {

//! Interface giving clients (RPC, Stratum v2 Template Provider in the future)
//! ability to create block templates.

class Mining
{
public:
    virtual ~Mining() {}

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

    /**
     * Check a block is completely valid from start to finish.
     * Only works on top of our current best block.
     * Does not check proof-of-work.
     *
     * @param[out] state details of why a block failed to validate
     * @param[in] block the block to validate
     * @param[in] check_merkle_root call CheckMerkleRoot()
     * @returns false if any of the checks fail
     */
    virtual bool testBlockValidity(BlockValidationState& state, const CBlock& block, bool check_merkle_root = true) = 0;

    //! Get internal node context. Useful for RPC and testing,
    //! but not accessible across processes.
    virtual node::NodeContext* context() { return nullptr; }
};

//! Return implementation of Mining interface.
std::unique_ptr<Mining> MakeMining(node::NodeContext& node);

} // namespace interfaces

#endif // BITCOIN_INTERFACES_MINING_H


Review comment (suggestion):
In commit "rpc: call TestBlockValidity via miner interface" (d8a3496b5ad27bea4c79ea0344f595cc1b95f0d3)

Not important, but it might be good to move the `state` output parameter last. The reason would be to work with the libmultiprocess code generator in case we want to expose this interface over IPC. The code generator only knows how to parse Cap'n Proto declarations, not C++ code, so when it encounters a Cap'n Proto method declaration with output parameters like:

```capnp
testBlockValidity @1 (block: Data, maxTxFee :Bool) -> (state: ValidationState, result :Bool);
```

it just assumes a corresponding C++ method exists with the listed input parameters first and output parameters last.

(Also I just noticed information about output parameters was changed in the developer notes. Suggestion to put output parameters last used used to be mentioned in the "internal interface" style section, but it looks like commit e66b321fd1ddfffd9bfc59d407ad8f03490b873c from #25092 turned that advice into a bigger, broader rule, which I'm not sure is a great change..)

Code after:
     */
    virtual std::unique_ptr<node::CBlockTemplate> createNewBlock(const CScript& script_pub_key, bool use_mempool = true) = 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
     */
    virtual bool processNewBlock(const std::shared_ptr<const CBlock>& block, bool* new_block) = 0;

    //! Return the number of transaction updates in the mempool,
    //! used to decide whether to make a new block template.
    virtual unsigned int getTransactionsUpdated() = 0;

    /**
     * Check a block is completely valid from start to finish.
     * Only works on top of our current best block.
     * Does not check proof-of-work.
     *
     * @param[out] state details of why a block failed to validate
     * @param[in] block the block to validate
     * @param[in] check_merkle_root call CheckMerkleRoot()
     * @returns false if any of the checks fail
     */
    virtual bool testBlockValidity(BlockValidationState& state, const CBlock& block, bool check_merkle_root = true) = 0;

    //! Get internal node context. Useful for RPC and testing,
    //! but not accessible across processes.
    virtual node::NodeContext* context() { return nullptr; }
};

//! Return implementation of Mining interface.
std::unique_ptr<Mining> MakeMining(node::NodeContext& node);

} // namespace interfaces

#endif // BITCOIN_INTERFACES_MINING_H