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.

13,072 bytes · SHA-256 793f2ee59ca9b349… · 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"""Test the -alertnotify, -blocknotify and -walletnotify options."""
6import os
7import platform
8
9from test_framework.address import ADDRESS_BCRT1_UNSPENDABLE
10from test_framework.blocktools import (
11    create_block,
12)
13from test_framework.descriptors import descsum_create
14from test_framework.extendedkey import ExtendedPrivateKey
15from test_framework.test_framework import BitcoinTestFramework
16from test_framework.util import (
17    assert_equal,
18)
19
20# Linux allow all characters other than \x00
21# Windows disallow control characters (0-31) and /\?%:|"<>
22FILE_CHAR_START = 32 if platform.system() == 'Windows' else 1
23FILE_CHAR_END = 128
24FILE_CHARS_DISALLOWED = '/\\?%*:|"<>' if platform.system() == 'Windows' else '/'
25UNCONFIRMED_HASH_STRING = 'unconfirmed'
26
27LARGE_WORK_INVALID_CHAIN_WARNING = (
28    "Warning: Found invalid chain more than 6 blocks longer than our best chain. This could be due to database corruption or consensus incompatibility with peers."
29)
30
31
32def notify_outputname(walletname, txid):
33    return txid if platform.system() == 'Windows' else f'{walletname}_{txid}'
34
35def shell_escape_posix(arg):
36    # Identical to ShellEscape() in the C++ code
37    return "'" + arg.replace("'", "'\"'\"'") + "'"
38
39
40class NotificationsTest(BitcoinTestFramework):
41    def set_test_params(self):
42        self.num_nodes = 2
43        self.setup_clean_chain = True
44        self.uses_wallet = None
45        self.noban_tx_relay = True
46
47    def setup_network(self):
48        self.wallet = ''.join(chr(i) for i in range(FILE_CHAR_START, FILE_CHAR_END) if chr(i) not in FILE_CHARS_DISALLOWED)
49        self.alertnotify_dir = os.path.join(self.options.tmpdir, "alertnotify")
50        self.alertnotify_file = os.path.join(self.alertnotify_dir, "alertnotify.txt")
51        self.blocknotify_dir = os.path.join(self.options.tmpdir, "blocknotify")
52        self.walletnotify_dir = os.path.join(self.options.tmpdir, "walletnotify")
53        self.shutdownnotify_dir = os.path.join(self.options.tmpdir, "shutdownnotify")
54        self.shutdownnotify_file = os.path.join(self.shutdownnotify_dir, "shutdownnotify.txt")
55        os.mkdir(self.alertnotify_dir)
56        os.mkdir(self.blocknotify_dir)
57        os.mkdir(self.walletnotify_dir)
58        os.mkdir(self.shutdownnotify_dir)
59
60        if platform.system() == 'Windows':
61            walletnotify_path = f"\"{os.path.join(self.walletnotify_dir, notify_outputname('%w', '%s'))}\""
62        else:
63            walletnotify_path = f"{shell_escape_posix(os.path.join(self.walletnotify_dir, ''))}{notify_outputname('%w', '%s')}"
64
65        # -alertnotify and -blocknotify on node0, walletnotify on node1
66        self.extra_args = [[
67            f"-alertnotify=echo %s >> \"{self.alertnotify_file}\"",
68            f"-blocknotify=echo > \"{os.path.join(self.blocknotify_dir, '%s')}\"",
69            f"-shutdownnotify=echo > \"{self.shutdownnotify_file}\"",
70        ], [
71            f"-walletnotify=echo %h_%b > {walletnotify_path}",
72        ]]
73        self.wallet_names = [self.default_wallet_name, self.wallet]
74        super().setup_network()
75
76    def run_test(self):
77        if self.is_wallet_compiled():
78            # Setup the descriptors to be imported to the wallet
79            xpriv = ExtendedPrivateKey.generate().to_string()
80            desc_imports = [{
81                "desc": descsum_create(f"wpkh({xpriv}/0/*)"),
82                "timestamp": 0,
83                "active": True,
84                "keypool": True,
85            },{
86                "desc": descsum_create(f"wpkh({xpriv}/1/*)"),
87                "timestamp": 0,
88                "active": True,
89                "keypool": True,
90                "internal": True,
91            }]
92            # Make the wallets and import the descriptors
93            # Ensures that node 0 and node 1 share the same wallet for the conflicting transaction tests below.
94            for i, name in enumerate(self.wallet_names):
95                self.nodes[i].createwallet(wallet_name=name, blank=True, load_on_startup=True)
96                self.nodes[i].importdescriptors(desc_imports)
97
98        self.log.info("test -blocknotify")
99        block_count = 10
100        blocks = self.generatetoaddress(self.nodes[1], block_count, self.nodes[1].getnewaddress() if self.is_wallet_compiled() else ADDRESS_BCRT1_UNSPENDABLE)
101
102        # wait at most 10 seconds for expected number of files before reading the content
103        self.wait_until(lambda: len(os.listdir(self.blocknotify_dir)) == block_count, timeout=10)
104
105        # directory content should equal the generated blocks hashes
106        assert_equal(sorted(blocks), sorted(os.listdir(self.blocknotify_dir)))
107
108        if self.is_wallet_compiled():
109            self.log.info("test -walletnotify")
110            # wait at most 10 seconds for expected number of files before reading the content
111            self.wait_until(lambda: len(os.listdir(self.walletnotify_dir)) == block_count, timeout=10)
112
113            # directory content should equal the generated transaction hashes
114            tx_details = list(map(lambda t: (t['txid'], t['blockheight'], t['blockhash']), self.nodes[1].listtransactions("*", block_count)))
115            self.expect_wallet_notify(tx_details)
116
117            self.log.info("test -walletnotify after rescan")
118            # rescan to force wallet notifications
119            self.nodes[1].rescanblockchain()
120            self.wait_until(lambda: len(os.listdir(self.walletnotify_dir)) == block_count, timeout=10)
121
122            self.connect_nodes(0, 1)
123
124            # directory content should equal the generated transaction hashes
125            tx_details = list(map(lambda t: (t['txid'], t['blockheight'], t['blockhash']), self.nodes[1].listtransactions("*", block_count)))
126            self.expect_wallet_notify(tx_details)
127
128            # Conflicting transactions tests.
129            # Generate spends from node 0, and check notifications
130            # triggered by node 1
131            self.log.info("test -walletnotify with conflicting transactions")
132            self.nodes[0].rescanblockchain()
133            self.generatetoaddress(self.nodes[0], 100, ADDRESS_BCRT1_UNSPENDABLE)
134
135            # Generate transaction on node 0, sync mempools, and check for
136            # notification on node 1.
137            tx1 = self.nodes[0].sendtoaddress(address=ADDRESS_BCRT1_UNSPENDABLE, amount=1, replaceable=True)
138            assert_equal(tx1 in self.nodes[0].getrawmempool(), True)
139            self.sync_mempools()
140            self.expect_wallet_notify([(tx1, -1, UNCONFIRMED_HASH_STRING)])
141
142            # Generate bump transaction, sync mempools, and check for bump1
143            # notification. In the future, per
144            # https://github.com/bitcoin/bitcoin/pull/9371, it might be better
145            # to have notifications for both tx1 and bump1.
146            bump1 = self.nodes[0].bumpfee(tx1)["txid"]
147            assert_equal(bump1 in self.nodes[0].getrawmempool(), True)
148            self.sync_mempools()
149            self.expect_wallet_notify([(bump1, -1, UNCONFIRMED_HASH_STRING)])
150
151            # Add bump1 transaction to new block, checking for a notification
152            # and the correct number of confirmations.
153            blockhash1 = self.generatetoaddress(self.nodes[0], 1, ADDRESS_BCRT1_UNSPENDABLE)[0]
154            blockheight1 = self.nodes[0].getblockcount()
155            self.sync_blocks()
156            self.expect_wallet_notify([(bump1, blockheight1, blockhash1)])
157            assert_equal(self.nodes[1].gettransaction(bump1)["confirmations"], 1)
158
159            # Generate a second transaction to be bumped.
160            tx2 = self.nodes[0].sendtoaddress(address=ADDRESS_BCRT1_UNSPENDABLE, amount=1, replaceable=True)
161            assert_equal(tx2 in self.nodes[0].getrawmempool(), True)
162            self.sync_mempools()
163            self.expect_wallet_notify([(tx2, -1, UNCONFIRMED_HASH_STRING)])
164
165            # Bump tx2 as bump2 and generate a block on node 0 while
166            # disconnected, then reconnect and check for notifications on node 1
167            # about newly confirmed bump2 and newly conflicted tx2.
168            self.disconnect_nodes(0, 1)
169            bump2 = self.nodes[0].bumpfee(tx2)["txid"]
170            blockhash2 = self.generatetoaddress(self.nodes[0], 1, ADDRESS_BCRT1_UNSPENDABLE, sync_fun=self.no_op)[0]
171            blockheight2 = self.nodes[0].getblockcount()
172            assert_equal(self.nodes[0].gettransaction(bump2)["confirmations"], 1)
173            assert_equal(tx2 in self.nodes[1].getrawmempool(), True)
174            self.connect_nodes(0, 1)
175            self.sync_blocks()
176            self.expect_wallet_notify([(bump2, blockheight2, blockhash2), (tx2, -1, UNCONFIRMED_HASH_STRING)])
177            assert_equal(self.nodes[1].gettransaction(bump2)["confirmations"], 1)
178
179            if platform.system() != 'Windows':
180                self.log.info("test -walletnotify replacement metacharacters in wallet name")
181                self.nodes[1].unloadwallet(self.wallet)
182                command_marker = os.path.join(self.options.tmpdir, "walletnotify_injected")
183                # The previous regex replacement expanded `$'` to the command suffix, breaking the shell-escaped wallet name's quote accounting
184                wallet_name = self.nodes[1].createwallet(f"$'$'; echo Pwned > {os.path.basename(command_marker)}; #")["name"]
185                txid = self.nodes[0].sendtoaddress(self.nodes[1].get_wallet_rpc(wallet_name).getnewaddress(), 1)
186                self.sync_mempools()
187                notify_path = os.path.join(self.walletnotify_dir, notify_outputname(wallet_name, txid))
188                self.wait_until(lambda: os.path.exists(command_marker) or os.path.exists(notify_path), timeout=10)
189                assert not os.path.exists(command_marker)
190                assert os.path.exists(notify_path)
191
192        self.log.info("test -alertnotify with large work invalid chain")
193        # create a bunch of invalid blocks
194        tip = self.nodes[0].getbestblockhash()
195        height = self.nodes[0].getblockcount() + 1
196        block_time = self.nodes[0].getblock(tip)['time'] + 1
197
198        invalid_blocks = []
199        for _ in range(7):  # invalid chain must be longer than 6 blocks to trigger warning
200            block = create_block(int(tip, 16), height=height, ntime=block_time)
201            # make block invalid by exceeding block subsidy
202            block.vtx[0].vout[0].nValue += 1
203            block.hashMerkleRoot = block.calc_merkle_root()
204            block.solve()
205            invalid_blocks.append(block)
206            tip = block.hash_hex
207            height += 1
208            block_time += 1
209
210        # submit headers of invalid blocks
211        for invalid_block in invalid_blocks:
212            self.nodes[0].submitheader(invalid_block.serialize().hex())
213        # submit invalid blocks in reverse order (tip first, to set m_best_invalid)
214        for invalid_block in reversed(invalid_blocks):
215            self.nodes[0].submitblock(invalid_block.serialize().hex())
216
217        self.wait_until(lambda: os.path.isfile(self.alertnotify_file), timeout=10)
218        self.wait_until(self.large_work_invalid_chain_warning_in_alert_file, timeout=10)
219
220        self.log.info("test -shutdownnotify")
221        self.stop_nodes()
222        self.wait_until(lambda: os.path.isfile(self.shutdownnotify_file), timeout=10)
223
224    def large_work_invalid_chain_warning_in_alert_file(self):
225        with open(self.alertnotify_file, 'r') as f:
226            alert_text = f.read()
227        return LARGE_WORK_INVALID_CHAIN_WARNING in alert_text
228
229    def expect_wallet_notify(self, tx_details):
230        self.wait_until(lambda: len(os.listdir(self.walletnotify_dir)) >= len(tx_details), timeout=10)
231        # Should have no more and no less files than expected
232        assert_equal(sorted(notify_outputname(self.wallet, tx_id) for tx_id, _, _ in tx_details), sorted(os.listdir(self.walletnotify_dir)))
233        # Should now verify contents of each file
234        for tx_id, blockheight, blockhash in tx_details:
235            fname = os.path.join(self.walletnotify_dir, notify_outputname(self.wallet, tx_id))
236            # Wait for the cached writes to hit storage
237            self.wait_until(lambda: os.path.getsize(fname) > 0, timeout=10)
238            with open(fname, 'rt') as f:
239                text = f.read()
240                # Universal newline ensures '\n' on 'nt'
241                assert_equal(text[-1], '\n')
242                text = text[:-1]
243                if platform.system() == 'Windows':
244                    # On Windows, echo as above will append a whitespace
245                    assert_equal(text[-1], ' ')
246                    text = text[:-1]
247                expected = str(blockheight) + '_' + blockhash
248                assert_equal(text, expected)
249
250        for tx_file in os.listdir(self.walletnotify_dir):

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.