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 server340 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.

16,640 bytes · SHA-256 a1b863764bc6e40e… · View upstream ↗

1// Copyright (c) 2009-2010 Satoshi Nakamoto
2// Copyright (c) 2009-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
6#ifndef BITCOIN_CHAIN_H
7#define BITCOIN_CHAIN_H
8
9#include <arith_uint256.h>
10#include <consensus/params.h>
11#include <flatfile.h>
12#include <kernel/cs_main.h>
13#include <primitives/block.h>
14#include <serialize.h>
15#include <sync.h>
16#include <uint256.h>
17#include <util/time.h>
18
19#include <algorithm>
20#include <cassert>
21#include <cstdint>
22#include <string>
23#include <vector>
24
25/**
26 * Maximum amount of time that a block timestamp is allowed to exceed the
27 * current time before the block will be accepted.
28 */
29inline constexpr int64_t MAX_FUTURE_BLOCK_TIME = 2 * 60 * 60;
30
31/**
32 * Timestamp window used as a grace period by code that compares external
33 * timestamps (such as timestamps passed to RPCs, or wallet key creation times)
34 * to block timestamps. This should be set at least as high as
35 * MAX_FUTURE_BLOCK_TIME.
36 */
37inline constexpr int64_t TIMESTAMP_WINDOW = MAX_FUTURE_BLOCK_TIME;
38//! Init values for CBlockIndex nSequenceId when loaded from disk
39inline constexpr int32_t SEQ_ID_BEST_CHAIN_FROM_DISK = 0;
40inline constexpr int32_t SEQ_ID_INIT_FROM_DISK = 1;
41
42enum BlockStatus : uint32_t {
43    //! Unused.
44    BLOCK_VALID_UNKNOWN      =    0,
45
46    //! Reserved (was BLOCK_VALID_HEADER).
47    BLOCK_VALID_RESERVED     =    1,
48
49    //! All parent headers found, difficulty matches, timestamp >= median previous. Implies all parents
50    //! are also at least TREE.
51    BLOCK_VALID_TREE         =    2,
52
53    /**
54     * Only first tx is coinbase, 2 <= coinbase input script length <= 100, transactions valid, no duplicate txids,
55     * sigops, size, merkle root. Implies all parents are at least TREE but not necessarily TRANSACTIONS.
56     *
57     * If a block's validity is at least VALID_TRANSACTIONS, CBlockIndex::nTx will be set. If a block and all previous
58     * blocks back to the genesis block or an assumeutxo snapshot block are at least VALID_TRANSACTIONS,
59     * CBlockIndex::m_chain_tx_count will be set.
60     */
61    BLOCK_VALID_TRANSACTIONS =    3,
62
63    //! Outputs do not overspend inputs, no double spends, coinbase output ok, no immature coinbase spends, BIP30.
64    //! Implies all previous blocks back to the genesis block or an assumeutxo snapshot block are at least VALID_CHAIN.
65    BLOCK_VALID_CHAIN        =    4,
66
67    //! Scripts & signatures ok. Implies all previous blocks back to the genesis block or an assumeutxo snapshot block
68    //! are at least VALID_SCRIPTS.
69    BLOCK_VALID_SCRIPTS      =    5,
70
71    //! All validity bits.
72    BLOCK_VALID_MASK         =   BLOCK_VALID_RESERVED | BLOCK_VALID_TREE | BLOCK_VALID_TRANSACTIONS |
73                                 BLOCK_VALID_CHAIN | BLOCK_VALID_SCRIPTS,
74
75    BLOCK_HAVE_DATA          =    8, //!< full block available in blk*.dat
76    BLOCK_HAVE_UNDO          =   16, //!< undo data available in rev*.dat
77    BLOCK_HAVE_MASK          =   BLOCK_HAVE_DATA | BLOCK_HAVE_UNDO,
78
79    BLOCK_FAILED_VALID       =   32, //!< stage after last reached validness failed
80    BLOCK_FAILED_CHILD       =   64, //!< Unused flag that was previously set when descending from failed block
81
82    BLOCK_OPT_WITNESS        =   128, //!< block data in blk*.dat was received with a witness-enforcing client
83
84    BLOCK_STATUS_RESERVED    =   256, //!< Unused flag that was previously set on assumeutxo snapshot blocks and their
85                                      //!< ancestors before they were validated, and unset when they were validated.
86};
87
88/** The block chain is a tree shaped structure starting with the
89 * genesis block at the root, with each block potentially having multiple
90 * candidates to be the next block. A blockindex may have multiple pprev pointing
91 * to it, but at most one of them can be part of the currently active branch.
92 */
93class CBlockIndex
94{
95public:
96    //! pointer to the hash of the block, if any. Memory is owned by this CBlockIndex
97    const uint256* phashBlock{nullptr};
98
99    //! pointer to the index of the predecessor of this block
100    CBlockIndex* pprev{nullptr};
101
102    //! pointer to the index of some further predecessor of this block
103    CBlockIndex* pskip{nullptr};
104
105    //! height of the entry in the chain. The genesis block has height 0
106    int nHeight{0};
107
108    //! Which # file this block is stored in (blk?????.dat)
109    int nFile GUARDED_BY(::cs_main){0};
110
111    //! Byte offset within blk?????.dat where this block's data is stored
112    uint64_t nDataPos GUARDED_BY(::cs_main){0};
113
114    //! Byte offset within rev?????.dat where this block's undo data is stored
115    uint64_t nUndoPos GUARDED_BY(::cs_main){0};
116
117    //! (memory only) Total amount of work (expected number of hashes) in the chain up to and including this block
118    arith_uint256 nChainWork{};
119
120    //! Number of transactions in this block. This will be nonzero if the block
121    //! reached the VALID_TRANSACTIONS level, and zero otherwise.
122    //! Note: in a potential headers-first mode, this number cannot be relied upon
123    unsigned int nTx{0};
124
125    //! (memory only) Number of transactions in the chain up to and including this block.
126    //! This value will be non-zero if this block and all previous blocks back
127    //! to the genesis block or an assumeutxo snapshot block have reached the
128    //! VALID_TRANSACTIONS level.
129    uint64_t m_chain_tx_count{0};
130
131    //! Verification status of this block. See enum BlockStatus
132    //!
133    //! Note: this value is modified to show BLOCK_OPT_WITNESS during UTXO snapshot
134    //! load to avoid a spurious startup failure requiring -reindex.
135    //! @sa NeedsRedownload
136    //! @sa ActivateSnapshot
137    uint32_t nStatus GUARDED_BY(::cs_main){0};
138
139    //! block header
140    int32_t nVersion{0};
141    uint256 hashMerkleRoot{};
142    uint32_t nTime{0};
143    uint32_t nBits{0};
144    uint32_t nNonce{0};
145
146    //! (memory only) Sequential id assigned to distinguish order in which blocks are received.
147    //! Initialized to SEQ_ID_INIT_FROM_DISK{1} when loading blocks from disk, except for blocks
148    //! belonging to the best chain which overwrite it to SEQ_ID_BEST_CHAIN_FROM_DISK{0}.
149    int32_t nSequenceId{SEQ_ID_INIT_FROM_DISK};
150
151    //! (memory only) Maximum nTime in the chain up to and including this block.
152    unsigned int nTimeMax{0};
153
154    explicit CBlockIndex(const CBlockHeader& block)
155        : nVersion{block.nVersion},
156          hashMerkleRoot{block.hashMerkleRoot},
157          nTime{block.nTime},
158          nBits{block.nBits},
159          nNonce{block.nNonce}
160    {
161    }
162
163    FlatFilePos GetBlockPos() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main)
164    {
165        AssertLockHeld(::cs_main);
166        FlatFilePos ret;
167        if (nStatus & BLOCK_HAVE_DATA) {
168            ret.nFile = nFile;
169            ret.nPos = nDataPos;
170        }
171        return ret;
172    }
173
174    FlatFilePos GetUndoPos() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main)
175    {
176        AssertLockHeld(::cs_main);
177        FlatFilePos ret;
178        if (nStatus & BLOCK_HAVE_UNDO) {
179            ret.nFile = nFile;
180            ret.nPos = nUndoPos;
181        }
182        return ret;
183    }
184
185    CBlockHeader GetBlockHeader() const
186    {
187        CBlockHeader block;
188        block.nVersion = nVersion;
189        if (pprev)
190            block.hashPrevBlock = pprev->GetBlockHash();
191        block.hashMerkleRoot = hashMerkleRoot;
192        block.nTime = nTime;
193        block.nBits = nBits;
194        block.nNonce = nNonce;
195        return block;
196    }
197
198    uint256 GetBlockHash() const
199    {
200        assert(phashBlock != nullptr);
201        return *phashBlock;
202    }
203
204    /**
205     * Check whether this block and all previous blocks back to the genesis block or an assumeutxo snapshot block have
206     * reached VALID_TRANSACTIONS and had transactions downloaded (and stored to disk) at some point.
207     *
208     * Does not imply the transactions are consensus-valid (ConnectTip might fail)
209     * Does not imply the transactions are still stored on disk. (IsBlockPruned might return true)
210     *
211     * Note that this will be true for the snapshot base block, if one is loaded, since its m_chain_tx_count value will have
212     * been set manually based on the related AssumeutxoData entry.
213     */
214    bool HaveNumChainTxs() const { return m_chain_tx_count != 0; }
215
216    NodeSeconds Time() const
217    {
218        return NodeSeconds{std::chrono::seconds{nTime}};
219    }
220
221    int64_t GetBlockTime() const
222    {
223        return (int64_t)nTime;
224    }
225
226    int64_t GetBlockTimeMax() const
227    {
228        return (int64_t)nTimeMax;
229    }
230
231    static constexpr int nMedianTimeSpan = 11;
232
233    int64_t GetMedianTimePast() const
234    {
235        int64_t pmedian[nMedianTimeSpan];
236        int64_t* pbegin = &pmedian[nMedianTimeSpan];
237        int64_t* pend = &pmedian[nMedianTimeSpan];
238
239        const CBlockIndex* pindex = this;
240        for (int i = 0; i < nMedianTimeSpan && pindex; i++, pindex = pindex->pprev)
241            *(--pbegin) = pindex->GetBlockTime();
242
243        std::sort(pbegin, pend);
244        return pbegin[(pend - pbegin) / 2];
245    }
246
247    std::string ToString() const;
248
249    //! Check whether this block index entry is valid up to the passed validity level.
250    bool IsValid(enum BlockStatus nUpTo) const

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

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.