66#define BITCOIN_INTERFACES_MINING_H
77
88#include < consensus/amount.h>
9+ #include < interfaces/handler.h>
910#include < interfaces/types.h>
1011#include < node/mining_types.h>
1112#include < primitives/block.h>
1213#include < primitives/transaction.h>
1314#include < uint256.h>
15+ #include < util/result.h>
1416#include < util/time.h>
1517
1618#include < cstdint>
19+ #include < functional>
1720#include < memory>
1821#include < optional>
1922#include < string>
@@ -29,6 +32,9 @@ namespace interfaces {
2932class BlockTemplate
3033{
3134public:
35+ using NextTemplateFn = std::function<void (std::unique_ptr<BlockTemplate>)>;
36+ using SubmitSolutionFn = std::function<void (bool )>;
37+
3238 virtual ~BlockTemplate () = default ;
3339
3440 virtual CBlockHeader getBlockHeader () = 0;
@@ -75,32 +81,39 @@ class BlockTemplate
7581 * the solved block is constructed and broadcast by multiple nodes
7682 * (e.g. both the miner who constructed the template and the pool).
7783 */
78- virtual bool submitSolution (uint32_t version, uint32_t timestamp, uint32_t nonce, CTransactionRef coinbase) = 0;
84+ /* *
85+ * Construct and broadcast the block asynchronously. The returned handler
86+ * cancels the submission before the callback runs.
87+ */
88+ virtual std::unique_ptr<Handler> submitSolutionAsync (uint32_t version, uint32_t timestamp, uint32_t nonce, CTransactionRef coinbase, SubmitSolutionFn fn) = 0;
7989
8090 /* *
81- * Waits for fees in the next block to rise, a new tip or the timeout.
91+ * Watches for fees in the next block to rise, a new tip or the timeout.
8292 *
8393 * @param[in] options Control the timeout (default forever) and by how much total fees
8494 * for the next block should rise (default infinite).
95+ * @param[in] fn Called with a new block template, or nullptr on
96+ * timeout or cancellation.
8597 *
86- * @returns a new BlockTemplate or nothing if the timeout occurs .
98+ * @returns a handler that cancels the watch before the callback runs .
8799 *
88100 * On testnet this will additionally return a template with difficulty 1 if
89101 * the tip is more than 20 minutes old.
90102 */
91- virtual std::unique_ptr<BlockTemplate> waitNext (node::BlockWaitOptions options = {}) = 0;
92-
93- /* *
94- * Interrupts the current wait for the next block template.
95- */
96- virtual void interruptWait () = 0;
103+ virtual std::unique_ptr<Handler> watchNext (node::BlockWaitOptions options, NextTemplateFn fn) = 0;
97104};
98105
99106// ! Interface giving clients (RPC, Stratum v2 Template Provider in the future)
100107// ! ability to create block templates.
101108class Mining
102109{
103110public:
111+ using TipChangedFn = std::function<void (std::optional<BlockRef>)>;
112+ using CreateBlockResult = util::Result<std::unique_ptr<BlockTemplate>>;
113+ using CreateBlockFn = std::function<void (CreateBlockResult)>;
114+ using CheckBlockFn = std::function<void (bool , std::string, std::string)>;
115+ using SubmitBlockFn = std::function<void (bool , std::string, std::string)>;
116+
104117 virtual ~Mining () = default ;
105118
106119 // ! If this chain is exclusively used for testing
@@ -112,85 +125,71 @@ class Mining
112125 // ! Returns the hash and height for the tip of this chain
113126 virtual std::optional<BlockRef> getTip () = 0;
114127
115- /* *
116- * Waits for the connected tip to change. During node initialization, this will
117- * wait until the tip is connected (regardless of `timeout`).
118- *
119- * @param[in] current_tip block hash of the current chain tip. Function waits
120- * for the chain tip to differ from this.
121- * @param[in] timeout how long to wait for a new tip (default is forever)
122- *
123- * @retval BlockRef hash and height of the current chain tip after this call.
124- * @retval std::nullopt if the node is shut down or interrupt() is called.
125- */
126- virtual std::optional<BlockRef> waitTipChanged (uint256 current_tip, MillisecondsDouble timeout = MillisecondsDouble::max()) = 0;
128+ // ! Watches for the connected tip to differ from current_tip. The returned
129+ // ! handler cancels the watch before the callback runs.
130+ virtual std::unique_ptr<Handler> watchTip (uint256 current_tip, MillisecondsDouble timeout, TipChangedFn fn) = 0;
127131
128- /* *
129- * Construct a new block template.
132+ /* *
133+ * Construct a new block template asynchronously .
130134 *
131135 * @param[in] options options for creating the block
132136 * @param[in] cooldown wait for tip to be connected and IBD to complete.
133137 * If the best header is ahead of the tip, wait for the
134138 * tip to catch up. It's recommended to disable this on
135139 * regtest and signets with only one miner, as these
136140 * could stall.
137- * @retval BlockTemplate a block template.
138- * @retval std::nullptr if the node is shut down or interrupt() is called.
139- */
140- virtual std::unique_ptr<BlockTemplate> createNewBlock (const node::BlockCreateOptions& options = {}, bool cooldown = true ) = 0;
141-
142- /* *
143- * Interrupts createNewBlock and waitTipChanged.
141+ * @param[in] fn called with a block template result. A successful result
142+ * may contain nullptr when the operation is cancelled or the
143+ * node is shutting down.
144+ *
145+ * @returns a handler that cancels the operation before the callback runs.
144146 */
145- virtual void interrupt ( ) = 0;
147+ virtual std::unique_ptr<Handler> createNewBlockAsync ( const node::BlockCreateOptions& options, bool cooldown, CreateBlockFn fn ) = 0;
146148
147149 /* *
148- * Checks if a given block is valid.
150+ * Checks if a given block is valid asynchronously .
149151 *
150152 * @param[in] block the block to check
151153 * @param[in] options verification options: the proof-of-work check can be
152154 * skipped in order to verify a template generated by
153155 * external software.
154- * @param[out] reason failure reason (BIP22)
155- * @param[out] debug more detailed rejection reason
156- * @returns whether the block is valid
156+ * @param[in] fn called with validity, failure reason (BIP22), and
157+ * more detailed rejection reason.
157158 *
158159 * For signets the challenge verification is skipped when check_pow is false.
159160 */
160- virtual bool checkBlock ( const CBlock& block, const node::BlockCheckOptions& options, std::string& reason, std::string& debug ) = 0;
161+ virtual std::unique_ptr<Handler> checkBlockAsync ( CBlock block, node::BlockCheckOptions options, CheckBlockFn fn ) = 0;
161162
162163 /* *
163- * Process a fully assembled block.
164+ * Process a fully assembled block asynchronously .
164165 *
165- * Similar to the submitblock RPC. Accepts a complete block, validates
166- * it, and if accepted as new, processes it into chainstate. Accepted
167- * blocks may then be announced to peers through normal validation signals.
166+ * Similar to the submitblock RPC. Accepts a complete block, validates it,
167+ * and if accepted as new, processes it into chainstate. Accepted blocks may
168+ * then be announced to peers through normal validation signals.
168169 *
169- * @param[in] block the complete block to submit
170- * @param[out] reason failure reason (BIP22)
171- * @param[out] debug more detailed rejection reason
172- * @returns true if the block was accepted as a new block. Returns
173- * false and sets reason if the block is a duplicate or
174- * the validation result is inconclusive.
170+ * @param[in] block the complete block to submit
171+ * @param[in] fn called with accepted, failure reason (BIP22), and more
172+ * detailed rejection reason. Accepted is false for duplicate
173+ * or inconclusive validation results.
175174 *
176175 * @note Unlike the submitblock RPC, this method does not call
177176 * UpdateUncommittedBlockStructures to add a missing coinbase witness
178177 * reserved value. Callers must submit a fully formed block, including
179178 * the coinbase witness when a witness commitment is present.
180179 */
181- virtual bool submitBlock ( const CBlock& block, std::string& reason, std::string& debug ) = 0;
180+ virtual std::unique_ptr<Handler> submitBlockAsync ( CBlock block, SubmitBlockFn fn ) = 0;
182181
183182 // ! Get internal node context. Useful for RPC and testing,
184183 // ! but not accessible across processes.
185- virtual const node::NodeContext* context () { return nullptr ; }
184+ virtual node::NodeContext* context () { return nullptr ; }
186185};
187186
188187// ! Return implementation of Mining interface.
189188// !
190189// ! @param[in] wait_loaded waits for chainstate data to be loaded before
191190// ! returning. Used to prevent external clients from
192191// ! being able to crash the node during startup.
193- std::unique_ptr<Mining> MakeMining (const node::NodeContext& node, bool wait_loaded= true );
192+ std::unique_ptr<Mining> MakeMining (node::NodeContext& node, bool wait_loaded = true );
194193
195194} // namespace interfaces
196195
0 commit comments