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.

48,220 bytes · SHA-256 3c985c512875547e… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2017-present 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"""Class for bitcoind node under test"""
6
7import contextlib
8import decimal
9import errno
10from enum import Enum
11import json
12import logging
13import os
14import platform
15import re
16import subprocess
17import tempfile
18import time
19import urllib.parse
20import collections
21import sys
22from collections.abc import Iterable
23from pathlib import Path
24
25from .authproxy import (
26    AuthServiceProxy,
27    JSONRPCException,
28    serialization_fallback,
29)
30from . import coverage
31from .messages import NODE_P2P_V2
32from .p2p import P2P_SERVICES, P2P_SUBVERSION
33from .util import (
34    MAX_NODES,
35    assert_equal,
36    assert_not_equal,
37    append_config,
38    delete_cookie_file,
39    get_auth_cookie,
40    rpc_port,
41    wait_until_helper_internal,
42    p2p_port,
43    tor_port,
44)
45
46BITCOIND_PROC_WAIT_TIMEOUT = 60
47# The size of the blocks xor key
48# from InitBlocksdirXorKey::xor_key.size()
49NUM_XOR_BYTES = 8
50# Many systems have a 128kB limit for a command size. Depending on the
51# platform, this limit may be larger or smaller. Moreover, when using the
52# 'bitcoin' command, it may internally insert more args, which must be
53# accounted for. There is no need to pick the largest possible value here
54# anyway and it should be fine to set it to 1kB in tests.
55TEST_CLI_MAX_ARG_SIZE = 1024
56
57# The null blocks key (all 0s)
58NULL_BLK_XOR_KEY = bytes([0] * NUM_XOR_BYTES)
59BITCOIN_PID_FILENAME_DEFAULT = "bitcoind.pid"
60
61if sys.platform.startswith("linux"):
62    UNIX_PATH_MAX = 108          # includes the trailing NUL
63elif sys.platform.startswith(("darwin", "freebsd", "netbsd", "openbsd")):
64    UNIX_PATH_MAX = 104
65else:                            # safest portable value
66    UNIX_PATH_MAX = 92
67
68
69class FailedToStartError(Exception):
70    """Raised when a node fails to start correctly."""
71
72
73class ErrorMatch(Enum):
74    FULL_TEXT = 1
75    FULL_REGEX = 2
76    PARTIAL_REGEX = 3
77
78
79RPCConnectionType = Enum("RPCConnectionType", ["AUTO", "AUTHPROXY", "CLI"])
80
81
82class TestNode():
83    """A class for representing a bitcoind node under test.
84
85    This class contains:
86
87    - state about the node (whether it's running, etc)
88    - a Python subprocess.Popen object representing the running process
89    - an RPC connection to the node
90    - one or more P2P connections to the node
91
92
93    To make things easier for the test writer, any unrecognised messages will
94    be dispatched to the RPC connection."""
95
96    def __init__(
97        self,
98        i,
99        datadir_path,
100        *,
101        chain,
102        rpchost,
103        timewait,
104        timeout_factor,
105        binaries,
106        coverage_dir,
107        cwd,
108        extra_conf=None,
109        extra_args=None,
110        use_cli=False,
111        version=None,
112        v2transport=False,
113        uses_wallet=False,
114        ipcbind=False,
115        use_gui=False,
116    ):
117        self.index = i
118        self.datadir_path = datadir_path
119        self.bitcoinconf = self.datadir_path / "bitcoin.conf"
120        self.stdout_dir = self.datadir_path / "stdout"
121        self.stderr_dir = self.datadir_path / "stderr"
122        self.chain = chain
123        self.rpchost = rpchost
124        self.rpc_timeout = timewait  # Already multiplied by timeout_factor
125        self.timeout_factor = timeout_factor
126        self.binaries = binaries
127        self.coverage_dir = coverage_dir
128        self.cwd = cwd
129        self.use_gui = use_gui
130        self.has_explicit_bind = False
131        if extra_conf is not None:
132            append_config(self.datadir_path, extra_conf)
133            # Remember if there is bind=... in the config file.
134            self.has_explicit_bind = any(e.startswith("bind=") for e in extra_conf)
135        # Most callers will just need to add extra args to the standard list below.
136        # For those callers that need more flexibility, they can just set the args property directly.
137        # Note that common args are set in the config file (see initialize_datadir)
138        self.extra_args = extra_args
139        self.version = version
140        # Configuration for logging is set as command-line args rather than in the bitcoin.conf file.
141        # This means that starting a bitcoind using the temp dir to debug a failed test won't
142        # spam debug.log.
143        self.args = self.binaries.node_argv(need_ipc=ipcbind, use_gui=use_gui) + [
144            f"-datadir={self.datadir_path}",
145            "-logtimemicros",
146            "-debug",
147            "-debugexclude=leveldb",
148            "-debugexclude=rand",
149            "-uacomment=testnode%d" % i,  # required for subversion uniqueness across peers
150        ]
151        if uses_wallet is not None and not uses_wallet:
152            self.args.append("-disablewallet")
153
154        self.ipc_tmp_dir = None
155        if ipcbind:
156            self.ipc_socket_path = self.chain_path / "node.sock"
157            if len(os.fsencode(self.ipc_socket_path)) < UNIX_PATH_MAX:
158                self.args.append("-ipcbind=unix")
159            else:
160                # Work around default CI path exceeding maximum socket path length.
161                self.ipc_tmp_dir = tempfile.TemporaryDirectory(prefix="test-ipc-")
162                self.ipc_socket_path = Path(self.ipc_tmp_dir.name) / "node.sock"
163                self.args.append(f"-ipcbind=unix:{self.ipc_socket_path}")
164
165        if self.version_is_at_least(190000):
166            self.args.append("-logthreadnames")
167        if self.version_is_at_least(219900):
168            self.args.append("-logsourcelocations")
169        if self.version_is_at_least(239000):
170            self.args.append("-loglevel=trace")
171        if self.version_is_at_least(290100):
172            self.args.append("-nologratelimit")
173
174        # Default behavior from global -v2transport flag is added to args to persist it over restarts.
175        # May be overwritten in individual tests, using extra_args.
176        self.default_to_v2 = v2transport
177        if self.version_is_at_least(260000):
178            # 26.0 and later support v2transport
179            if v2transport:
180                self.args.append("-v2transport=1")
181            else:
182                self.args.append("-v2transport=0")
183        # if v2transport is requested via global flag but not supported for node version, ignore it
184
185        self.cli = None
186        self.use_cli = use_cli
187
188        self.running = False
189        self.process = None
190        self.rpc_connected = False
191        self._rpc = None # Should usually not be accessed directly in tests to allow for --usecli mode
192        self.reuse_http_connections = True # Must be set before create_new_rpc_connection(), i.e. before restarting node
193        self.url = None
194        self.log = logging.getLogger('TestFramework.node%d' % i)
195
196        self.p2ps = []
197
198        self.mocktime = None
199
200    AddressKeyPair = collections.namedtuple('AddressKeyPair', ['address', 'key'])
201    PRIV_KEYS = [
202            # address , privkey
203            AddressKeyPair('mjTkW3DjgyZck4KbiRusZsqTgaYTxdSz6z', 'cVpF924EspNh8KjYsfhgY96mmxvT6DgdWiTYMtMjuM74hJaU5psW'),
204            AddressKeyPair('msX6jQXvxiNhx3Q62PKeLPrhrqZQdSimTg', 'cUxsWyKyZ9MAQTaAhUQWJmBbSvHMwSmuv59KgxQV7oZQU3PXN3KE'),
205            AddressKeyPair('mnonCMyH9TmAsSj3M59DsbH8H63U3RKoFP', 'cTrh7dkEAeJd6b3MRX9bZK8eRmNqVCMH3LSUkE3dSFDyzjU38QxK'),
206            AddressKeyPair('mqJupas8Dt2uestQDvV2NH3RU8uZh2dqQR', 'cVuKKa7gbehEQvVq717hYcbE9Dqmq7KEBKqWgWrYBa2CKKrhtRim'),
207            AddressKeyPair('msYac7Rvd5ywm6pEmkjyxhbCDKqWsVeYws', 'cQDCBuKcjanpXDpCqacNSjYfxeQj8G6CAtH1Dsk3cXyqLNC4RPuh'),
208            AddressKeyPair('n2rnuUnwLgXqf9kk2kjvVm8R5BZK1yxQBi', 'cQakmfPSLSqKHyMFGwAqKHgWUiofJCagVGhiB4KCainaeCSxeyYq'),
209            AddressKeyPair('myzuPxRwsf3vvGzEuzPfK9Nf2RfwauwYe6', 'cQMpDLJwA8DBe9NcQbdoSb1BhmFxVjWD5gRyrLZCtpuF9Zi3a9RK'),
210            AddressKeyPair('mumwTaMtbxEPUswmLBBN3vM9oGRtGBrys8', 'cSXmRKXVcoouhNNVpcNKFfxsTsToY5pvB9DVsFksF1ENunTzRKsy'),
211            AddressKeyPair('mpV7aGShMkJCZgbW7F6iZgrvuPHjZjH9qg', 'cSoXt6tm3pqy43UMabY6eUTmR3eSUYFtB2iNQDGgb3VUnRsQys2k'),
212            AddressKeyPair('mq4fBNdckGtvY2mijd9am7DRsbRB4KjUkf', 'cN55daf1HotwBAgAKWVgDcoppmUNDtQSfb7XLutTLeAgVc3u8hik'),
213            AddressKeyPair('mpFAHDjX7KregM3rVotdXzQmkbwtbQEnZ6', 'cT7qK7g1wkYEMvKowd2ZrX1E5f6JQ7TM246UfqbCiyF7kZhorpX3'),
214            AddressKeyPair('mzRe8QZMfGi58KyWCse2exxEFry2sfF2Y7', 'cPiRWE8KMjTRxH1MWkPerhfoHFn5iHPWVK5aPqjW8NxmdwenFinJ'),
215    ]
216
217    def get_deterministic_priv_key(self):
218        """Return a deterministic priv key in base58, that only depends on the node's index"""
219        assert_equal(len(self.PRIV_KEYS), MAX_NODES)
220        return self.PRIV_KEYS[self.index]
221
222    def _node_msg(self, msg: str) -> str:
223        """Return a modified msg that identifies this node by its index as a debugging aid."""
224        return "[node %d] %s" % (self.index, msg)
225
226    def _raise_assertion_error(self, msg: str):
227        """Raise an AssertionError with msg modified to identify this node."""
228        raise AssertionError(self._node_msg(msg))
229
230    def __del__(self):
231        # Ensure that we don't leave any bitcoind processes lying around after
232        # the test ends
233        if self.process:
234            # Should only happen on test failure
235            # Avoid using logger, as that may have already been shutdown when
236            # this destructor is called.
237            print(self._node_msg("Cleaning up leftover process"), file=sys.stderr)
238            self.process.kill()
239
240    def __getattr__(self, name):
241        """Dispatches any unrecognised messages to the RPC connection or a CLI instance."""
242        if self.use_cli:
243            return getattr(self.cli, name)
244        else:
245            assert self.rpc_connected and self._rpc is not None, self._node_msg("Error: no RPC connection")
246            return getattr(self._rpc, name)
247
248    def start(self, extra_args=None, *, cwd=None, stdout=None, stderr=None, env=None, **kwargs):
249        """Start the node."""
250        if extra_args is None:

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.