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.

5,958 bytes · SHA-256 a5dc1d2c2b53b772… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) The Bitcoin Core developers
3# Distributed under the MIT software license.
4
5"""
6Ensures that UTXO unserialization errors abort the node, and does not
7cause a consensus divergence.
8
9A valid UTXO is created and shared between two nodes. The raw database
10entry is then deliberately modified on one node so it can no longer be
11deserialized. When the other node spends that UTXO and mines a block,
12the node with the unserializable entry must abort during block connection
13rather than silently treating the coin as absent and marking the block
14BLOCK_FAILED_VALID, which would cause it to permanently diverge from the
15network's best chain.
16"""
17
18try:
19    import plyvel  # type: ignore[import]
20except ImportError:
21    plyvel = None
22
23from test_framework.blocktools import COINBASE_MATURITY
24from test_framework.test_framework import BitcoinTestFramework, SkipTest
25from test_framework.util import assert_equal
26from test_framework.wallet import MiniWallet
27
28
29class UTXOAbortOnErrorTest(BitcoinTestFramework):
30    def set_test_params(self):
31        self.setup_clean_chain = True
32        self.num_nodes = 2
33
34    def skip_test_if_missing_module(self):
35        if plyvel is None:
36            raise SkipTest("plyvel not available (pip install plyvel)")
37
38    def setup_network(self):
39        self.setup_nodes() # Start with nodes disconnected
40
41    def run_test(self):
42        node0, node1 = self.nodes
43
44        self.log.info("Mining mature coinbase on node0")
45        wallet0 = MiniWallet(node0)
46        self.generate(wallet0, COINBASE_MATURITY + 1, sync_fun=self.no_op)
47        assert_equal(node0.getblockcount(), COINBASE_MATURITY + 1)
48
49        # The coinbase of block 1 is now mature. This is the UTXO we will
50        # make unserializable on node0 and spend on node1.
51        coinbase_txid = node0.getblock(node0.getblockhash(1))['tx'][0]
52        assert node0.gettxout(coinbase_txid, 0) is not None, f"Expected UTXO {coinbase_txid}:0 to exist in UTXO set"
53
54        self.log.info("Preparing a spend of the mature coinbase UTXO (not broadcast)")
55        utxo = wallet0.get_utxo(txid=coinbase_txid, vout=0, mark_as_spent=False)
56        spend_tx_hex = wallet0.create_self_transfer(utxo_to_spend=utxo)['hex']
57
58        self.log.info("Sync node1 up to the tip, then isolate nodes")
59        self.connect_nodes(0, 1)
60        self.sync_blocks()
61        assert_equal(node1.getblockcount(), COINBASE_MATURITY + 1)
62        self.disconnect_nodes(0, 1)
63
64        self.log.info("Make UTXO unserializable in node0 database")
65        self.stop_node(0)
66
67        # LevelDB key for the CoinEntry serialization:
68        # key = DB_COIN (0x43='C') || txid (32 bytes) || VARINT(vout=0)
69        coin_key = b'\x43' + bytes.fromhex(coinbase_txid)[::-1] + b'\x00'
70        chainstate_path = str(node0.chain_path / "chainstate")
71
72        # Update entry to mimic an incompatible serialization format
73        with plyvel.DB(chainstate_path, create_if_missing=False, compression=None) as db:
74            existing_value = db.get(coin_key)
75            assert existing_value is not None, f"UTXO {coinbase_txid}:0 not found in db"
76
77            # Write a single-byte value. After XOR deobfuscation this is still just one
78            # byte, far too short for a valid Coin (which needs height VARINT + amount
79            # VARINT + script at minimum). Deserialization will throw "end of data" when
80            # trying to read beyond the first field.
81            db.put(coin_key, b'\x00')
82
83        self.log.info("Restart node0 — the unserializable entry is only visible during block validation, not at startup")
84        self.start_node(0)
85
86        # Individual coin values are not read at startup; only block validation
87        # touches them. The node starts cleanly regardless of the tampered entry.
88        assert_equal(node0.getblockcount(), COINBASE_MATURITY + 1)
89
90        # Now spend the corrupted UTXO
91        self.log.info("node1 broadcasts the spend and mines a block")
92        node1.sendrawtransaction(spend_tx_hex)
93        spending_block_hash = self.generate(node1, 1, sync_fun=self.no_op)[0]
94        assert_equal(node1.getblockcount(), COINBASE_MATURITY + 2)
95
96        self.log.info("Connect node0 to node1 — node0 must abort when it tries to connect the spending block")
97        # Verify that the unserializable entry triggers the expected error and is
98        # never silently misreported as a missing input (bad-txns-inputs-missingorspent),
99        # which would indicate the previous silent-divergence behaviour.
100        with node0.assert_debug_log(expected_msgs=["Error reading from database: Coin deserialization failure"],
101                                    unexpected_msgs=["bad-txns-inputs-missingorspent"]):
102            try:
103                self.connect_nodes(0, 1)
104            except Exception:
105                pass # node0 may validly abort before connect_nodes returns
106
107            # Confirm node0 aborted with SIGABRT
108            self.wait_until(lambda: self.nodes[0].is_node_stopped(
109                expected_ret_code=-6,
110                expected_stderr="Error: Error reading from database, shutting down.",
111            ))
112
113        self.log.info("node0 aborted cleanly — no silent divergence occurred")
114
115        self.log.info("Restart node0 and verify the spending block was not permanently marked invalid")
116        self.start_node(0)
117        assert_equal(node0.getblockcount(), COINBASE_MATURITY + 1)
118
119        # If BLOCK_FAILED_VALID had been written to disk, the node would be
120        # permanently stuck on a stale tip even after the tampered entry is resolved.
121        tips = node0.getchaintips()
122        permanently_invalid = [
123            t for t in tips
124            if t['hash'] == spending_block_hash and t['status'] == 'invalid'
125        ]
126        assert len(permanently_invalid) == 0, f"Spending block {spending_block_hash} must not be marked BLOCK_FAILED_VALID"
127
128
129if __name__ == '__main__':
130    UTXOAbortOnErrorTest(__file__).main()
131

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.