READ THE CODE

Inside Bitcoin

The code behind the network, with room to understand it.

Stable release v32.1bitcoin/bitcoin · f0de87f04062 ↗3,020 source files · 47.5 MB stored on the server440 file guides

Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.

42,395 bytes · SHA-256 0ad5e0e524d90a78… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) The Bitcoin Core developers
3# Distributed under the MIT software license, see the accompanying
4# file COPYING or http://www.opensource.org/licenses/mit-license.php.
5"""Test the IPC (multiprocess) Mining interface."""
6import asyncio
7import time
8from contextlib import AsyncExitStack
9from copy import deepcopy
10from decimal import Decimal
11from io import BytesIO
12from test_framework.blocktools import (
13    NULL_OUTPOINT,
14    script_BIP34_coinbase_height,
15    WITNESS_COMMITMENT_HEADER,
16)
17from test_framework.messages import (
18    CBlockHeader,
19    COIN,
20    CTransaction,
21    CTxIn,
22    CTxInWitness,
23    CTxOut,
24    DEFAULT_BLOCK_RESERVED_WEIGHT,
25    MAX_BLOCK_SIGOPS_COST,
26    MAX_BLOCK_WEIGHT,
27    from_hex,
28    msg_headers,
29    ser_uint256,
30)
31from test_framework.test_framework import BitcoinTestFramework
32from test_framework.util import (
33    assert_equal,
34    assert_greater_than_or_equal,
35    assert_not_equal,
36)
37from test_framework.wallet import MiniWallet
38from test_framework.p2p import P2PInterface
39from test_framework.ipc_util import (
40    assert_capnp_failed,
41    assert_create_new_block_fails,
42    destroying,
43    load_capnp_modules,
44    make_mining_ctx,
45    mining_create_block_template,
46    mining_get_block,
47    mining_get_coinbase_tx,
48    mining_wait_next_template,
49    wait_and_do,
50)
51
52# Test may be skipped and not have capnp installed
53try:
54    import capnp  # type: ignore[import] # noqa: F401
55except ModuleNotFoundError:
56    pass
57
58
59class IPCMiningTest(BitcoinTestFramework):
60
61    def skip_test_if_missing_module(self):
62        self.skip_if_no_ipc()
63        self.skip_if_no_py_capnp()
64
65    def set_test_params(self):
66        self.num_nodes = 3
67
68    def setup_nodes(self):
69        self.extra_init = [{"ipcbind": True}, {}, {"ipcbind": True}]
70        super().setup_nodes()
71        # Use this function to also load the capnp modules (we cannot use set_test_params for this,
72        # as it is being called before knowing whether capnp is available).
73        self.capnp_modules = load_capnp_modules(self.config)
74
75    async def build_coinbase_test(self, template, ctx, miniwallet, extra_nonce=b""):
76        self.log.debug("Build coinbase transaction using getCoinbaseTx()")
77        assert template is not None
78        coinbase_res = await mining_get_coinbase_tx(template, ctx)
79        coinbase_tx = CTransaction()
80        coinbase_tx.version = coinbase_res.version
81        coinbase_tx.vin = [CTxIn()]
82        coinbase_tx.vin[0].prevout = NULL_OUTPOINT
83        coinbase_tx.vin[0].nSequence = coinbase_res.sequence
84
85        # Verify there's no dummy extraNonce in the coinbase scriptSig
86        current_block_height = self.nodes[0].getchaintips()[0]["height"]
87        bip34_prefix = script_BIP34_coinbase_height(current_block_height + 1, padding=False)
88        assert_equal(coinbase_res.scriptSigPrefix, bip34_prefix)
89
90        # Typically a mining pool appends its name and an extraNonce
91        coinbase_tx.vin[0].scriptSig = coinbase_res.scriptSigPrefix + extra_nonce
92
93        # We currently always provide a coinbase witness, even for empty
94        # blocks, but this may change, so always check:
95        has_witness = coinbase_res.witness is not None
96        if has_witness:
97            coinbase_tx.wit.vtxinwit = [CTxInWitness()]
98            coinbase_tx.wit.vtxinwit[0].scriptWitness.stack = [coinbase_res.witness]
99
100        # First output is our payout
101        coinbase_tx.vout = [CTxOut()]
102        coinbase_tx.vout[0].scriptPubKey = miniwallet.get_output_script()
103        coinbase_tx.vout[0].nValue = coinbase_res.blockRewardRemaining
104        # Add SegWit OP_RETURN. This is currently always present even for
105        # empty blocks, but this may change.
106        for output_data in coinbase_res.requiredOutputs:
107            output = CTxOut()
108            output.deserialize(BytesIO(output_data))
109            coinbase_tx.vout.append(output)
110
111        coinbase_tx.nLockTime = coinbase_res.lockTime
112        return coinbase_tx
113
114    async def build_candidate_block(self, template, ctx, extra_nonce=b""):
115        """Build a complete block from a remote BlockTemplate.
116
117        The returned block replaces the dummy coinbase from CreateNewBlock()
118        with one constructed from getCoinbaseTx().
119        """
120        block = await mining_get_block(template, ctx)
121        coinbase = await self.build_coinbase_test(
122            template, ctx, self.miniwallet, extra_nonce=extra_nonce)
123        # Reduce payout for balance comparison simplicity.
124        coinbase.vout[0].nValue = COIN
125        block.vtx[0] = coinbase
126        block.hashMerkleRoot = block.calc_merkle_root()
127        return block
128
129    async def assert_submit_block(self, mining, ctx, block, *, result, reason="", debug=""):
130        submit = await mining.submitBlock(ctx, block.serialize())
131        assert_equal(submit.result, result)
132        assert_equal(submit.reason, reason)
133        assert_equal(submit.debug, debug)
134
135    def run_mining_interface_test(self):
136        """Test Mining interface methods."""
137        self.log.info("Running Mining interface test")
138        block_hash_size = 32
139
140        async def async_routine():
141            ctx, mining = await make_mining_ctx(self)
142            blockref = await mining.getTip(ctx)
143            current_block_height = self.nodes[0].getchaintips()[0]["height"]
144            assert_equal(blockref.result.height, current_block_height)
145
146            self.log.debug("Mine a block")
147            newblockref = (await wait_and_do(
148                mining.waitTipChanged(ctx, blockref.result.hash, self.default_ipc_timeout),
149                lambda: self.generate(self.nodes[0], 1))).result
150            assert_equal(len(newblockref.hash), block_hash_size)
151            assert_equal(newblockref.height, current_block_height + 1)
152            self.log.debug("Wait for timeout")
153            oldblockref = (await mining.waitTipChanged(ctx, newblockref.hash, self.default_ipc_timeout)).result
154            assert_equal(len(newblockref.hash), block_hash_size)
155            assert_equal(oldblockref.hash, newblockref.hash)
156            assert_equal(oldblockref.height, newblockref.height)
157
158            self.log.debug("interrupt() should abort waitTipChanged()")
159            async def wait_for_tip():
160                long_timeout = max(self.default_ipc_timeout, 60000.0)  # at least 1 minute
161                result = (await mining.waitTipChanged(ctx, newblockref.hash, long_timeout)).result
162                # Unlike a timeout, interrupt() returns an empty BlockRef.
163                assert_equal(len(result.hash), 0)
164            await wait_and_do(wait_for_tip(), mining.interrupt())
165
166        asyncio.run(capnp.run(async_routine()))
167
168    def run_early_startup_test(self):
169        """Make sure mining.createNewBlock safely returns on early startup as
170        soon as mining interface is available """
171        self.log.info("Running Mining interface early startup test")
172
173        node = self.nodes[0]
174        self.stop_node(node.index)
175        node.start()
176
177        async def async_routine():
178            while True:
179                try:
180                    ctx, mining = await make_mining_ctx(self)
181                    break
182                except (ConnectionRefusedError, FileNotFoundError):
183                    # Poll quickly to connect as soon as socket becomes
184                    # available but without using a lot of CPU
185                    await asyncio.sleep(0.005)
186
187            opts = self.capnp_modules['mining'].BlockCreateOptions()
188            await mining.createNewBlock(ctx, opts)
189
190        asyncio.run(capnp.run(async_routine()))
191
192        # Reconnect nodes so next tests are happy
193        node.wait_for_rpc_connection()
194        self.connect_nodes(1, 0)
195        # Restarting node 0 drops its P2P connection to the rest of the test
196        # chain. Restore the synced 0-1-2 topology before later tests split
197        # node 2 off for submitBlock checks.
198        self.sync_all()
199
200    def run_block_template_test(self):
201        """Test BlockTemplate interface methods."""
202        self.log.info("Running BlockTemplate interface test")
203        block_header_size = 80
204
205        async def async_routine():
206            ctx, mining = await make_mining_ctx(self)
207
208            async with AsyncExitStack() as stack:
209                self.log.debug("createNewBlock() should wait if tip is still updating")
210                self.disconnect_nodes(0, 1)
211                node1_block_hash = self.generate(self.nodes[1], 1, sync_fun=self.no_op)[0]
212                header = from_hex(CBlockHeader(), self.nodes[1].getblockheader(node1_block_hash, False))
213                header_only_peer = self.nodes[0].add_p2p_connection(P2PInterface())
214                header_only_peer.send_and_ping(msg_headers([header]))
215                start = time.time()
216                async with destroying((await mining.createNewBlock(ctx, self.default_block_create_options)).result, ctx):
217                    pass
218                # Lower-bound only: a heavily loaded CI host might still exceed 0.9s
219                # even without the cooldown, so this can miss regressions but avoids
220                # spurious failures.
221                assert_greater_than_or_equal(time.time() - start, 0.9)
222
223                self.log.debug("createNewBlock() should wake up promptly after tip advances")
224                success = False
225                duration = 0.0
226                async def wait_fn():
227                    nonlocal success, duration
228                    start = time.time()
229                    res = await mining.createNewBlock(ctx, self.default_block_create_options)
230                    duration = time.time() - start
231                    success = res._has("result")
232                def do_fn():
233                    block_hex = self.nodes[1].getblock(node1_block_hash, False)
234                    self.nodes[0].submitblock(block_hex)
235                await wait_and_do(wait_fn(), do_fn)
236                assert_equal(success, True)
237                if self.options.timeout_factor <= 1:
238                    assert duration < 3.0, f"createNewBlock took {duration:.2f}s, did not wake up promptly after tip advances"
239                else:
240                    self.log.debug("Skipping strict wake-up duration check because timeout_factor > 1")
241
242                self.log.debug("interrupt() should abort createNewBlock() during cooldown")
243                async def create_block():
244                    result = await mining.createNewBlock(ctx, self.default_block_create_options)
245                    # interrupt() causes createNewBlock to return nullptr
246                    assert_equal(result._has("result"), False)
247
248                await wait_and_do(create_block(), mining.interrupt())
249
250                header_only_peer.peer_disconnect()

src/wallet/receive.cpp

src/wallet/coinselection.cpp

src/consensus/validation.h

src/primitives/transaction.cpp

src/script/descriptor.cpp

src/bitcoin-cli.cpp

src/rpc/blockchain.cpp

src/rpc/rawtransaction.cpp

src/init.cpp

src/crypto/sha256.cpp

src/consensus/merkle.h

src/consensus/tx_check.h

src/consensus/tx_verify.h

src/policy/feerate.h

src/policy/feerate.cpp

src/primitives/transaction_identifier.h

src/chainparamsbase.h

src/chainparamsbase.cpp

src/util/moneystr.cpp

src/crypto/ripemd160.h

src/crypto/sha1.h

src/crypto/sha512.h

src/crypto/hmac_sha256.h

src/crypto/hmac_sha512.h

src/crypto/hmac_sha256.cpp

src/crypto/hmac_sha512.cpp

src/crypto/hkdf_sha256_32.h

src/crypto/hkdf_sha256_32.cpp

src/support/cleanse.h

src/support/cleanse.cpp

src/crypto/siphash.cpp

src/crypto/muhash.h

src/crypto/chacha20.h

src/crypto/poly1305.h

src/crypto/chacha20poly1305.h

src/crypto/chacha20poly1305.cpp

src/util/chaintype.cpp

src/util/obfuscation.h

src/util/byte_units.h

src/util/overflow.h

src/blockencodings.cpp

src/net_permissions.cpp

src/policy/packages.cpp

src/policy/rbf.cpp

src/policy/truc_policy.cpp

src/policy/ephemeral_policy.cpp

src/policy/settings.cpp

src/policy/policy.cpp

src/node/transaction.cpp

src/node/coin.cpp

src/rpc/client.cpp

src/rpc/external_signer.cpp

src/rpc/request.cpp

src/rpc/server_util.cpp

src/rpc/fees.cpp

src/rpc/output_script.cpp

src/rpc/rawtransaction_util.cpp

src/rpc/rawtransaction_util.h

src/rpc/register.h

src/rpc/request.h

src/rpc/server_util.h

src/rpc/protocol.h

src/rpc/server.h

src/rpc/signmessage.cpp

src/rpc/txoutproof.cpp

src/rpc/util.cpp

src/rpc/util.h

src/wallet/rpc/addresses.cpp

src/wallet/rpc/backup.cpp

src/wallet/rpc/coins.cpp

src/wallet/rpc/encrypt.cpp

src/wallet/rpc/signmessage.cpp

src/wallet/rpc/util.cpp

src/wallet/rpc/util.h

src/wallet/coincontrol.cpp

src/wallet/coincontrol.h

src/wallet/context.cpp

src/wallet/context.h

src/wallet/crypter.cpp

src/wallet/crypter.h

src/wallet/db.cpp

src/wallet/export.cpp

src/wallet/external_signer_scriptpubkeyman.cpp

src/wallet/rpc/spend.cpp

src/wallet/rpc/transactions.cpp

src/wallet/rpc/wallet.cpp

src/wallet/feebumper.cpp

src/wallet/feebumper.h

src/index/base.h

src/index/base.cpp

src/index/txindex.h

src/index/txindex.cpp

src/index/txindex_key.h

src/index/txospenderindex.h

src/index/txospenderindex.cpp

src/index/blockfilterindex.h

src/index/blockfilterindex.cpp

src/index/coinstatsindex.h

src/index/coinstatsindex.cpp

src/index/db_key.h

src/index/disktxpos.h

src/kernel/chain.cpp

src/kernel/chain.h

src/kernel/checks.cpp

src/kernel/checks.h

src/kernel/context.cpp

src/kernel/context.h

src/kernel/cs_main.cpp

src/kernel/cs_main.h

src/kernel/disconnected_transactions.cpp

src/kernel/disconnected_transactions.h

src/kernel/mempool_removal_reason.cpp

src/kernel/mempool_removal_reason.h

src/kernel/coinstats.cpp

src/kernel/coinstats.h

src/kernel/chainparams.cpp

src/kernel/chainparams.h

src/wallet/sqlite.cpp

src/wallet/sqlite.h

src/wallet/transaction.cpp

src/wallet/transaction.h

src/wallet/dump.cpp

src/wallet/dump.h

src/wallet/init.cpp

src/wallet/walletutil.cpp

src/wallet/walletutil.h

src/wallet/wallettool.cpp

src/wallet/wallettool.h

src/wallet/export.h

src/wallet/migrate.cpp

src/wallet/migrate.h

src/wallet/db.h

src/wallet/walletdb.cpp

src/wallet/interfaces.cpp

src/wallet/scriptpubkeyman.cpp

src/wallet/scriptpubkeyman.h

src/kernel/bitcoinkernel.cpp

src/kernel/bitcoinkernel.h

src/kernel/bitcoinkernel_wrapper.h

src/node/chainstate.cpp

src/node/chainstate.h

src/node/blockstorage.cpp

src/node/blockstorage.h

src/node/mempool_persist.cpp

src/node/mempool_persist.h

src/node/utxo_snapshot.cpp

src/node/utxo_snapshot.h

src/node/kernel_notifications.cpp

src/node/kernel_notifications.h

src/node/blockmanager_args.cpp

src/kernel/blockmanager_opts.h

src/util/expected.cpp

src/policy/settings.h

src/util/types.h

src/kernel/messagestartchars.h

src/kernel/warning.h

src/util/exception.h

src/common/license_info.h

src/node/coins_view_args.h

src/node/database_args.h

src/util/batchpriority.h

src/util/ui_change_type.h

src/node/coins_view_args.cpp

src/node/peerman_args.h

src/util/serfloat.h

src/node/blockmanager_args.h

src/node/database_args.cpp

src/util/overloaded.h

src/interfaces/types.h

src/node/chainstatemanager_args.h

src/node/minisketchwrapper.h

src/util/macros.h

src/util/syserror.h

src/common/run_command.h

src/util/bytevectorhash.cpp

src/node/mempool_persist_args.cpp

src/util/exec.h

src/util/rbf.h

src/crypto/hex_base.h

src/node/mempool_persist_args.h

src/interfaces/echo.h

src/util/any.h

src/util/batchpriority.cpp

src/util/threadnames.h

src/node/coin.h

src/node/mempool_args.h

src/util/asmap.h

src/util/bytevectorhash.h

src/node/context.cpp

src/util/insert.h

src/util/readwritefile.h

src/node/peerman_args.cpp

src/node/interface_ui.cpp

src/interfaces/handler.h

src/node/mining_args.h

src/util/hasher.cpp

src/common/init.h

src/kernel/mempool_limits.h

src/common/system.h

src/crypto/sha3.h

src/util/threadinterrupt.cpp

src/node/protocol_version.h

src/util/exception.cpp

src/common/messages.h

src/node/connection_types.cpp

src/util/bip32.h

src/common/license_info.cpp

src/util/stdmutex.h

src/common/run_command.cpp

src/util/check.cpp

src/util/golombrice.h

src/node/types.h

src/node/timeoffsets.h

src/util/readwritefile.cpp

src/util/fastrange.h

src/util/signalinterrupt.h

src/util/task_runner.h

src/util/syserror.cpp

src/common/interfaces.cpp

src/common/types.h

src/util/threadinterrupt.h

src/kernel/chainstatemanager_opts.h

src/node/psbt.h

src/policy/ephemeral_policy.h

src/util/trace.h

src/common/url.cpp

src/kernel/mempool_options.h

src/util/serfloat.cpp

src/kernel/notifications_interface.h

src/node/timeoffsets.cpp

src/node/warnings.cpp

src/util/hash_type.h

src/crypto/hex_base.cpp

src/node/eviction.h

src/util/tokenbucket.h

src/crypto/aes.h

src/common/pcp.h

src/util/feefrac.cpp

src/node/transaction.h

src/util/threadnames.cpp

src/common/signmessage.h

src/util/exec.cpp

src/util/signalinterrupt.cpp

src/clientversion.cpp

src/common/signmessage.cpp

src/compat/assumptions.h

src/compat/byteswap.h

src/deploymentinfo.cpp

src/deploymentinfo.h

src/deploymentstatus.cpp

src/deploymentstatus.h

src/dummywallet.cpp

src/external_signer.h

src/init/bitcoin-gui.cpp

src/init/bitcoin-node.cpp

src/init/bitcoin-qt.cpp

src/init/bitcoin-wallet.cpp

src/init/bitcoind.cpp

src/init/common.h

src/interfaces/init.h

src/interfaces/ipc.h

src/key_io.h

src/logging/categories.h

src/logging/timer.h

src/mapport.h

src/musig.h

src/net_permissions.h

src/netgroup.h

src/netmessagemaker.h

src/node/chainstatemanager_args.cpp

src/node/connection_types.h

src/node/context.h

src/node/interface_ui.h

src/node/mempool_args.cpp

src/node/mining_args.cpp

src/node/minisketchwrapper.cpp

src/node/txreconciliation.h

src/policy/fees/estimator_args.cpp

src/policy/fees/estimator_args.h

src/policy/fees/estimator_man.cpp

src/policy/fees/estimator_man.h

src/policy/packages.h

src/policy/rbf.h

src/policy/truc_policy.h

src/pow.h

src/primitives/block.cpp

src/randomenv.h

src/rest.h

src/script/keyorigin.h

src/script/parsing.cpp

src/script/parsing.h

src/script/script_error.h

src/script/sigcache.cpp

src/script/sigcache.h

src/script/solver.h

src/script/verify_flags.h

src/semaphore_grant.h

src/signet.h

src/span.h

src/support/allocators/secure.h

src/support/allocators/zeroafterfree.h

src/util/tokenpipe.cpp

src/util/translation.h

src/util/vector.h

src/versionbits.h

src/versionbits_impl.h

src/wallet/external_signer_scriptpubkeyman.h

src/wallet/fees.h

src/wallet/load.h

src/wallet/receive.h

src/wallet/rpc/wallet.h

src/wallet/types.h

src/walletinitinterface.h

src/zmq/zmqabstractnotifier.cpp

Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.

Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.