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.

10,530 bytes · SHA-256 13de0034eb8f41e3… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2015-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"""Utilities for manipulating blocks and transactions."""
6
7import struct
8import time
9import unittest
10
11from .address import (
12    address_to_scriptpubkey,
13    key_to_p2sh_p2wpkh,
14    key_to_p2wpkh,
15    script_to_p2sh_p2wsh,
16    script_to_p2wsh,
17)
18from .messages import (
19    CBlock,
20    COIN,
21    COutPoint,
22    CTransaction,
23    CTxIn,
24    CTxInWitness,
25    CTxOut,
26    SEQUENCE_FINAL,
27    hash256,
28    ser_uint256,
29    tx_from_hex,
30    uint256_from_compact,
31    WITNESS_SCALE_FACTOR,
32    MAX_SEQUENCE_NONFINAL,
33)
34from .script import (
35    CScript,
36    CScriptNum,
37    CScriptOp,
38    OP_0,
39    OP_RETURN,
40    OP_TRUE,
41)
42from .script_util import (
43    key_to_p2pk_script,
44    key_to_p2wpkh_script,
45    keys_to_multisig_script,
46    script_to_p2wsh_script,
47)
48from .util import assert_equal
49
50MAX_BLOCK_SIGOPS = 20000
51MAX_BLOCK_SIGOPS_WEIGHT = MAX_BLOCK_SIGOPS * WITNESS_SCALE_FACTOR
52MAX_STANDARD_TX_SIGOPS = 4000
53MAX_STANDARD_TX_WEIGHT = 400000
54
55# Genesis block time (regtest)
56TIME_GENESIS_BLOCK = 1296688602
57
58MAX_FUTURE_BLOCK_TIME = 2 * 60 * 60
59
60# Coinbase transaction outputs can only be spent after this number of new blocks (network rule)
61COINBASE_MATURITY = 100
62
63# From BIP141
64WITNESS_COMMITMENT_HEADER = b"\xaa\x21\xa9\xed"
65
66NULL_OUTPOINT = COutPoint(0, 0xffffffff)
67
68NORMAL_GBT_REQUEST_PARAMS = {"rules": ["segwit"]}
69VERSIONBITS_LAST_OLD_BLOCK_VERSION = 4
70MIN_BLOCKS_TO_KEEP = 288
71
72REGTEST_RETARGET_PERIOD = 150
73
74REGTEST_N_BITS = 0x207fffff  # difficulty retargeting is disabled in REGTEST chainparams"
75REGTEST_TARGET = 0x7fffff0000000000000000000000000000000000000000000000000000000000
76assert_equal(uint256_from_compact(REGTEST_N_BITS), REGTEST_TARGET)
77
78DIFF_1_N_BITS = 0x1d00ffff
79DIFF_1_TARGET = 0x00000000ffff0000000000000000000000000000000000000000000000000000
80assert_equal(uint256_from_compact(DIFF_1_N_BITS), DIFF_1_TARGET)
81
82DIFF_4_N_BITS = 0x1c3fffc0
83DIFF_4_TARGET = int(DIFF_1_TARGET / 4)
84assert_equal(uint256_from_compact(DIFF_4_N_BITS), DIFF_4_TARGET)
85
86# From BIP325
87SIGNET_HEADER = b"\xec\xc7\xda\xa2"
88
89# Number of blocks to create in temporary blockchain branch for reorg testing
90FORK_LENGTH = 10
91
92def nbits_str(nbits):
93    return f"{nbits:08x}"
94
95def target_str(target):
96    return f"{target:064x}"
97
98def create_block(hashprev=None, coinbase=None, *, ntime=None, height=None, version=None, tmpl=None, txlist=None):
99    """Create a block (with regtest difficulty)."""
100    block = CBlock()
101    if tmpl is None:
102        tmpl = {}
103    block.nVersion = version or tmpl.get('version') or VERSIONBITS_LAST_OLD_BLOCK_VERSION
104    block.nTime = ntime or tmpl.get('curtime') or int(time.time() + 600)
105    block.hashPrevBlock = hashprev or int(tmpl['previousblockhash'], 0x10)
106    if tmpl and tmpl.get('bits') is not None:
107        block.nBits = struct.unpack('>I', bytes.fromhex(tmpl['bits']))[0]
108    else:
109        block.nBits = REGTEST_N_BITS
110    if coinbase is None:
111        coinbase = create_coinbase(height=height or tmpl["height"])
112    block.vtx.append(coinbase)
113    if txlist:
114        for tx in txlist:
115            if type(tx) is str:
116                tx = tx_from_hex(tx)
117            block.vtx.append(tx)
118    block.hashMerkleRoot = block.calc_merkle_root()
119    return block
120
121def create_empty_fork(node, fork_length=FORK_LENGTH):
122    '''
123        Creates a fork using node's chaintip as the starting point.
124        Returns a list of blocks to submit in order.
125    '''
126    tip = int(node.getbestblockhash(), 16)
127    height = node.getblockcount()
128    block_time = node.getblock(node.getbestblockhash())['time'] + 1
129
130    blocks = []
131    for _ in range(fork_length):
132        block = create_block(tip, height=height + 1, ntime=block_time)
133        block.solve()
134        blocks.append(block)
135        tip = block.hash_int
136        block_time += 1
137        height += 1
138
139    return blocks
140
141def get_witness_script(witness_root, witness_nonce):
142    witness_commitment = hash256(ser_uint256(witness_root) + ser_uint256(witness_nonce))
143    output_data = WITNESS_COMMITMENT_HEADER + witness_commitment
144    return CScript([OP_RETURN, output_data])
145
146def add_witness_commitment(block, nonce=0):
147    """Add a witness commitment to the block's coinbase transaction.
148
149    According to BIP141, blocks with witness rules active must commit to the
150    hash of all in-block transactions including witness."""
151    # First calculate the merkle root of the block's
152    # transactions, with witnesses.
153    witness_nonce = nonce
154    witness_root = block.calc_witness_merkle_root()
155    # witness_nonce should go to coinbase witness.
156    block.vtx[0].wit.vtxinwit = [CTxInWitness()]
157    block.vtx[0].wit.vtxinwit[0].scriptWitness.stack = [ser_uint256(witness_nonce)]
158
159    # witness commitment is the last OP_RETURN output in coinbase
160    block.vtx[0].vout.append(CTxOut(0, get_witness_script(witness_root, witness_nonce)))
161    block.hashMerkleRoot = block.calc_merkle_root()
162
163
164def script_BIP34_coinbase_height(height, *, padding=True):
165    if height <= 16:
166        res = CScriptOp.encode_op_n(height)
167        if padding:
168            # Append dummy extraNonce to increase scriptSig size to 2 (see bad-cb-length consensus rule)
169            return CScript([res, OP_0])
170        return CScript([res])
171    return CScript([CScriptNum(height)])
172
173
174def create_coinbase(height, pubkey=None, *, script_pubkey=None, extra_output_script=None, fees=0, nValue=50, halving_period=REGTEST_RETARGET_PERIOD):
175    """Create a coinbase transaction.
176
177    If pubkey is passed in, the coinbase output will be a P2PK output;
178    otherwise an anyone-can-spend output.
179
180    If extra_output_script is given, make a 0-value output to that
181    script. This is useful to pad block weight/sigops as needed. """
182    coinbase = CTransaction()
183    coinbase.nLockTime = height - 1
184    coinbase.vin.append(CTxIn(NULL_OUTPOINT, script_BIP34_coinbase_height(height), MAX_SEQUENCE_NONFINAL))
185    coinbaseoutput = CTxOut()
186    coinbaseoutput.nValue = nValue * COIN
187    if nValue == 50:
188        halvings = int(height / halving_period)
189        coinbaseoutput.nValue >>= halvings
190        coinbaseoutput.nValue += fees
191    if pubkey is not None:
192        coinbaseoutput.scriptPubKey = key_to_p2pk_script(pubkey)
193    elif script_pubkey is not None:
194        coinbaseoutput.scriptPubKey = script_pubkey
195    else:
196        coinbaseoutput.scriptPubKey = CScript([OP_TRUE])
197    coinbase.vout = [coinbaseoutput]
198    if extra_output_script is not None:
199        coinbaseoutput2 = CTxOut()
200        coinbaseoutput2.nValue = 0
201        coinbaseoutput2.scriptPubKey = extra_output_script
202        coinbase.vout.append(coinbaseoutput2)
203    return coinbase
204
205def create_tx_with_script(prevtx, n, script_sig=b"", *, amount, output_script=None):
206    """Return one-input, one-output transaction object
207       spending the prevtx's n-th output with the given amount.
208
209       Can optionally pass scriptPubKey and scriptSig, default is anyone-can-spend output.
210    """
211    if output_script is None:
212        output_script = CScript()
213    tx = CTransaction()
214    assert n < len(prevtx.vout)
215    tx.vin.append(CTxIn(COutPoint(prevtx.txid_int, n), script_sig, SEQUENCE_FINAL))
216    tx.vout.append(CTxOut(amount, output_script))
217    return tx
218
219def get_legacy_sigopcount_block(block, accurate=True):
220    count = 0
221    for tx in block.vtx:
222        count += get_legacy_sigopcount_tx(tx, accurate)
223    return count
224
225def get_legacy_sigopcount_tx(tx, accurate=True):
226    count = 0
227    for i in tx.vout:
228        count += i.scriptPubKey.GetSigOpCount(accurate)
229    for j in tx.vin:
230        # scriptSig might be of type bytes, so convert to CScript for the moment
231        count += CScript(j.scriptSig).GetSigOpCount(accurate)
232    return count
233
234def witness_script(use_p2wsh, pubkey):
235    """Create a scriptPubKey for a pay-to-witness TxOut.
236
237    This is either a P2WPKH output for the given pubkey, or a P2WSH output of a
238    1-of-1 multisig for the given pubkey. Returns the hex encoding of the
239    scriptPubKey."""
240    if not use_p2wsh:
241        # P2WPKH instead
242        pkscript = key_to_p2wpkh_script(pubkey)
243    else:
244        # 1-of-1 multisig
245        witness_script = keys_to_multisig_script([pubkey])
246        pkscript = script_to_p2wsh_script(witness_script)
247    return pkscript.hex()
248
249def create_witness_tx(node, use_p2wsh, utxo, pubkey, encode_p2sh, amount):
250    """Return a transaction (in hex) that spends the given utxo to a segwit output.

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.