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.

29,282 bytes · SHA-256 c456da7fbad0692d… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2014-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"""Helpful routines for regression testing."""
6
7from base64 import b64encode
8from copy import copy
9from decimal import Decimal
10from subprocess import CalledProcessError
11import hashlib
12import inspect
13import json
14import logging
15import os
16import pathlib
17import platform
18import random
19import re
20import shlex
21import time
22import types
23
24from .descriptors import descsum_create
25from collections.abc import Callable
26from typing import Optional, Union
27
28SATOSHI_PRECISION = Decimal('0.00000001')
29
30logger = logging.getLogger("TestFramework.utils")
31
32class JSONRPCException(Exception):
33    def __init__(self, rpc_error, http_status=None):
34        self.error = rpc_error
35        self.http_status = http_status
36
37        # throw KeyError if any required fields are missing
38        copied_error = copy(rpc_error)
39        message = copied_error.pop("message")
40        code = copied_error.pop("code")
41        extra = f'{copied_error}' if copied_error else ''
42        super().__init__(f"{message} ({code}) {extra} [http_status={http_status}]")
43
44# Assert functions
45##################
46
47
48def assert_approx(v, vexp, vspan=0.00001):
49    """Assert that `v` is within `vspan` of `vexp`"""
50    if isinstance(v, Decimal) or isinstance(vexp, Decimal):
51        v=Decimal(v)
52        vexp=Decimal(vexp)
53        vspan=Decimal(vspan)
54    if v < vexp - vspan:
55        raise AssertionError("%s < [%s..%s]" % (str(v), str(vexp - vspan), str(vexp + vspan)))
56    if v > vexp + vspan:
57        raise AssertionError("%s > [%s..%s]" % (str(v), str(vexp - vspan), str(vexp + vspan)))
58
59
60def assert_fee_amount(fee, tx_size, feerate_BTC_kvB):
61    """Assert the fee is in range."""
62    assert isinstance(tx_size, int)
63    target_fee = get_fee(tx_size, feerate_BTC_kvB)
64    if fee < target_fee:
65        raise AssertionError("Fee of %s BTC too low! (Should be %s BTC)" % (str(fee), str(target_fee)))
66    # allow the wallet's estimation to be at most 2 bytes off
67    high_fee = get_fee(tx_size + 2, feerate_BTC_kvB)
68    if fee > high_fee:
69        raise AssertionError("Fee of %s BTC too high! (Should be %s BTC)" % (str(fee), str(target_fee)))
70
71
72def summarise_dict_differences(thing1, thing2):
73    if not isinstance(thing1, dict) or not isinstance(thing2, dict):
74        return thing1, thing2
75    d1, d2 = {}, {}
76    for k in sorted(thing1.keys()):
77        if k not in thing2:
78            d1[k] = thing1[k]
79        elif thing1[k] != thing2[k]:
80            d1[k], d2[k] = summarise_dict_differences(thing1[k], thing2[k])
81    for k in sorted(thing2.keys()):
82        if k not in thing1:
83            d2[k] = thing2[k]
84    return d1, d2
85
86def assert_equal(thing1, thing2, *args):
87    if thing1 != thing2 and not args and isinstance(thing1, dict) and isinstance(thing2, dict):
88        d1,d2 = summarise_dict_differences(thing1, thing2)
89        if d1 != thing1 or d2 != thing2:
90            raise AssertionError(f"not({thing1!s} == {thing2!s})\n  in particular not({d1!s} == {d2!s})")
91        else:
92            raise AssertionError(f"not({thing1!s} == {thing2!s})")
93    if thing1 != thing2 or any(thing1 != arg for arg in args):
94        raise AssertionError("not(%s)" % " == ".join(str(arg) for arg in (thing1, thing2) + args))
95
96def assert_not_equal(thing1, thing2, *, error_message=""):
97    if thing1 == thing2:
98        raise AssertionError(f"Both values are {thing1}{f', {error_message}' if error_message else ''}")
99
100
101def assert_greater_than(thing1, thing2):
102    if thing1 <= thing2:
103        raise AssertionError("%s <= %s" % (str(thing1), str(thing2)))
104
105
106def assert_greater_than_or_equal(thing1, thing2):
107    if thing1 < thing2:
108        raise AssertionError("%s < %s" % (str(thing1), str(thing2)))
109
110
111def assert_raises(exc, fun, *args, **kwds):
112    assert_raises_message(exc, None, fun, *args, **kwds)
113
114
115def assert_raises_message(exc, message, fun, *args, **kwds):
116    try:
117        fun(*args, **kwds)
118    except JSONRPCException:
119        raise AssertionError("Use assert_raises_rpc_error() to test RPC failures")
120    except exc as e:
121        if message is not None and message not in str(e):
122            raise AssertionError("Expected substring not found in exception:\n"
123                                 f"substring: '{message}'\nexception: {e!r}.")
124    except Exception as e:
125        raise AssertionError("Unexpected exception raised: " + type(e).__name__)
126    else:
127        raise AssertionError("No exception raised")
128
129
130def assert_raises_process_error(returncode: int, output: str, fun: Callable, *args, **kwds):
131    """Execute a process and asserts the process return code and output.
132
133    Calls function `fun` with arguments `args` and `kwds`. Catches a CalledProcessError
134    and verifies that the return code and output are as expected. Throws AssertionError if
135    no CalledProcessError was raised or if the return code and output are not as expected.
136
137    Args:
138        returncode: the process return code.
139        output: [a substring of] the process output.
140        fun: the function to call. This should execute a process.
141        args*: positional arguments for the function.
142        kwds**: named arguments for the function.
143    """
144    try:
145        fun(*args, **kwds)
146    except CalledProcessError as e:
147        if returncode != e.returncode:
148            raise AssertionError("Unexpected returncode %i" % e.returncode)
149        if output not in e.output:
150            raise AssertionError(f"Expected substring not found in: {e.output!r}")
151    else:
152        raise AssertionError("No exception raised")
153
154
155def assert_raises_rpc_error(code: Optional[int], message: Optional[str], fun: Callable, *args, **kwds):
156    """Run an RPC and verify that a specific JSONRPC exception code and message is raised.
157
158    Calls function `fun` with arguments `args` and `kwds`. Catches a JSONRPCException
159    and verifies that the error code and message are as expected. Throws AssertionError if
160    no JSONRPCException was raised or if the error code/message are not as expected.
161
162    Args:
163        code: the error code returned by the RPC call (defined in src/rpc/protocol.h).
164            Set to None if checking the error code is not required.
165        message: [a substring of] the error string returned by the RPC call.
166            Set to None if checking the error string is not required.
167        fun: the function to call. This should be the name of an RPC.
168        args*: positional arguments for the function.
169        kwds**: named arguments for the function.
170    """
171    assert try_rpc(code, message, fun, *args, **kwds), "No exception raised"
172
173
174def try_rpc(code, message, fun, *args, **kwds):
175    """Tries to run an rpc command.
176
177    Test against error code and message if the rpc fails.
178    Returns whether a JSONRPCException was raised."""
179    try:
180        fun(*args, **kwds)
181    except JSONRPCException as e:
182        # JSONRPCException was thrown as expected. Check the message and code values are correct.
183        if (message is not None) and (message not in e.error['message']):
184            raise AssertionError(
185                "Expected substring not found in error message:\nsubstring: '{}'\nerror message: '{}'.".format(
186                    message, e.error['message']))
187        if (code is not None) and (code != e.error["code"]):
188            raise AssertionError("Unexpected JSONRPC error code %i" % e.error["code"])
189        return True
190    except Exception as e:
191        raise AssertionError("Unexpected exception raised: " + type(e).__name__)
192    else:
193        return False
194
195
196def assert_is_hex_string(string):
197    try:
198        int(string, 16)
199    except Exception as e:
200        raise AssertionError("Couldn't interpret %r as hexadecimal; raised: %s" % (string, e))
201
202
203def assert_is_hash_string(string, length=64):
204    if not isinstance(string, str):
205        raise AssertionError("Expected a string, got type %r" % type(string))
206    elif length and len(string) != length:
207        raise AssertionError("String of length %d expected; got %d" % (length, len(string)))
208    elif not re.match('[abcdef0-9]+$', string):
209        raise AssertionError("String %r contains invalid characters for a hash." % string)
210
211
212def assert_array_result(object_array, to_match, expected, should_not_find=False):
213    """
214        Pass in array of JSON objects, a dictionary with key/value pairs
215        to match against, and another dictionary with expected key/value
216        pairs.
217        If the should_not_find flag is true, to_match should not be found
218        in object_array
219        """
220    if should_not_find:
221        assert_equal(expected, {})
222    num_matched = 0
223    for item in object_array:
224        all_match = True
225        for key, value in to_match.items():
226            if item[key] != value:
227                all_match = False
228        if not all_match:
229            continue
230        elif should_not_find:
231            num_matched = num_matched + 1
232        for key, value in expected.items():
233            if item[key] != value:
234                raise AssertionError("%s : expected %s=%s" % (str(item), str(key), str(value)))
235            num_matched = num_matched + 1
236    if num_matched == 0 and not should_not_find:
237        raise AssertionError("No objects matched %s" % (str(to_match)))
238    if num_matched > 0 and should_not_find:
239        raise AssertionError("Objects were found %s" % (str(to_match)))
240
241
242# Utility functions
243###################
244
245
246def check_json_precision():
247    """Make sure json library being used does not lose precision converting BTC values"""
248    n = Decimal("20000000.00000003")
249    satoshis = int(json.loads(json.dumps(float(n))) * 1.0e8)
250    if satoshis != 2000000000000003:

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.