Inside Bitcoin
Opening the selected file…
Inside Bitcoin
Opening the selected file…
The code behind the network, with room to understand it.
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.
502```shell503# For single target run with the target of choice504LLVM_PROFILE_FILE="$(pwd)/build/raw_profile_data/txorphan.profraw" ./build/test/fuzz/test_runner.py ../qa-assets/fuzz_corpora txorphan505# If running for multiple targets506LLVM_PROFILE_FILE="$(pwd)/build/raw_profile_data/%m_%p.profraw" ./build/test/fuzz/test_runner.py ../qa-assets/fuzz_corpora507# Merge profiles508llvm-profdata merge build/raw_profile_data/*.profraw -o build/coverage.profdata509```511Generate report:513```shell514llvm-cov show \515--object=build/bin/fuzz \516-Xdemangler=llvm-cxxfilt \517--instr-profile=build/coverage.profdata \518--ignore-filename-regex="src/crc32c/|src/leveldb/|src/minisketch/|src/secp256k1/|src/test/" \519--format=html \520--show-instantiation-summary \521--show-line-counts-or-regions \522--show-expansions \523--output-dir=build/coverage_report \524--project-title="Bitcoin Core Fuzz Coverage Report"525```527The generated coverage report can be accessed at `build/coverage_report/index.html`.529### Using IWYU531The [`include-what-you-use`](https://github.com/include-what-you-use/include-what-you-use) tool (IWYU)532helps to enforce the source code organization [policy](#source-code-organization) in this repository.534To reproduce the IWYU CI job locally, run:535```bash536env -i HOME="$HOME" PATH="$PATH" USER="$USER" MAKEJOBS="-j1" FILE_ENV="./ci/test/00_setup_env_native_iwyu.sh" ./ci/test_run_all.sh || echo "IWYU failed"537```539In some cases, IWYU might suggest headers that seem unnecessary at first glance, but are actually required.540For example, a macro may use a symbol that requires its own include. Another example is passing a string literal541to a function that accepts a `std::string` parameter. An implicit conversion occurs at the callsite using the542`std::string` constructor, which makes the corresponding header required. We accept these suggestions as is.544If the provided IWYU CI job still produces a false positive, reduce it to a minimal reproducer and report it upstream.546Use IWYU pragmas sparingly.548Use `IWYU pragma: keep` only as a narrow workaround when needed.550Use `IWYU pragma: associated` only when IWYU cannot infer the intended associated header.552Use `IWYU pragma: export` very sparingly, as this enforces transitive inclusion of headers and undermines the specific purpose of IWYU.554The acceptable cases for using `IWYU pragma: export` are:5551. Facade headers. For example, see [`compat/compat.h`](/src/compat/compat.h).5562. Drop-in replacement headers. For example, see [`util/time.h`](/src/util/time.h).5573. Presenting a complete interface across multiple headers.559For IWYU pragmas, prefer adding a nearby source comment that explains why the annotation is needed.561### Performance profiling with perf563Profiling is a good way to get a precise idea of where time is being spent in564code. One tool for doing profiling on Linux platforms is called565[`perf`](https://www.brendangregg.com/perf.html). It can observe a running566process and sample (at some frequency) where its execution is.568Perf installation is contingent on which kernel version you're running; see569[this thread](https://askubuntu.com/questions/50145/how-to-install-perf-monitoring-tool)570for specific instructions.572Certain kernel parameters may need to be set for perf to be able to inspect the573running process's stack.575```sh576$ sudo sysctl -w kernel.perf_event_paranoid=-1577$ sudo sysctl -w kernel.kptr_restrict=0578```580Make sure you [understand the security581trade-offs](https://lwn.net/Articles/420403/) of setting these kernel582parameters.584To profile a running bitcoind process for 60 seconds, you could use an585invocation of `perf record` like this:587```sh588$ perf record \589-g --call-graph dwarf --per-thread -F 140 \590-p `pgrep bitcoind` -- sleep 60591```593You could then analyze the results by running:595```sh596perf report --stdio | c++filt | less597```599or using a graphical tool like [Hotspot](https://github.com/KDAB/hotspot).601### Valgrind603Valgrind is a programming tool for memory debugging, memory leak detection, and604profiling. The repo contains a Valgrind suppressions file605([`valgrind.supp`](/test/sanitizer_suppressions/valgrind.supp))606which includes known Valgrind warnings in our dependencies that cannot be fixed607in-tree. Example use:609```shell610$ valgrind --suppressions=test/sanitizer_suppressions/valgrind.supp build/bin/test_bitcoin611$ valgrind --suppressions=test/sanitizer_suppressions/valgrind.supp --leak-check=full \612--show-leak-kinds=all build/bin/test_bitcoin --log_level=test_suite613$ valgrind -v --leak-check=full build/bin/bitcoind -printtoconsole614$ ./build/test/functional/test_runner.py --valgrind615```617### Sanitizers619Bitcoin Core can be compiled with various "sanitizers" enabled, which add620instrumentation for issues regarding things like memory safety, thread race621conditions, or undefined behavior. This is controlled with the622`-DSANITIZERS` cmake build flag, which should be a comma separated list of623sanitizers to enable. The sanitizer list should correspond to supported624`-fsanitize=` options in your compiler. These sanitizers have runtime overhead,625so they are most useful when testing changes or producing debugging builds.627Some examples:629```bash630# Enable both the address sanitizer and the undefined behavior sanitizer631cmake -B build -DSANITIZERS=address,undefined633# Enable the thread sanitizer634cmake -B build -DSANITIZERS=thread635```637If you are compiling with GCC you will typically need to install corresponding638"san" libraries to actually compile with these flags, e.g. libasan for the639address sanitizer, libtsan for the thread sanitizer, and libubsan for the640undefined sanitizer. If you are missing required libraries, the build641will fail with a linker error when testing the sanitizer flags.643The test suite should pass cleanly with the `thread` and `undefined` sanitizers. You644may need to use a suppressions file, see `test/sanitizer_suppressions`. They may be645used as follows:646```bash647export LSAN_OPTIONS="suppressions=$(pwd)/test/sanitizer_suppressions/lsan"648export TSAN_OPTIONS="suppressions=$(pwd)/test/sanitizer_suppressions/tsan:halt_on_error=1:second_deadlock_stack=1"649export UBSAN_OPTIONS="suppressions=$(pwd)/test/sanitizer_suppressions/ubsan:print_stacktrace=1:halt_on_error=1:report_error_type=1"650```652See the CI config for more examples, and upstream documentation for more information653about any additional options.655Not all sanitizer options can be enabled at the same time, e.g. trying to build656with `-DSANITIZERS=address,thread` will fail in the build as657these sanitizers are mutually incompatible. Refer to your compiler manual to658learn more about these options and which sanitizers are supported by your659compiler.661Additional resources:663* [AddressSanitizer](https://clang.llvm.org/docs/AddressSanitizer.html)664* [LeakSanitizer](https://clang.llvm.org/docs/LeakSanitizer.html)665* [MemorySanitizer](https://clang.llvm.org/docs/MemorySanitizer.html)666* [ThreadSanitizer](https://clang.llvm.org/docs/ThreadSanitizer.html)667* [UndefinedBehaviorSanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html)668* [GCC Instrumentation Options](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html)669* [Google Sanitizers Wiki](https://github.com/google/sanitizers/wiki)671# Development guidelines673A few non-style-related recommendations for developers, as well as points to674pay attention to for reviewers of Bitcoin Core code.676## General Testing678As a rule of thumb, an externally observable change (new feature, bug fix, or679changed default) should be accompanied by an automated test.680New tests are usually not needed for behavior-preserving work that is easy to681validate, such as moving code, renaming, or mechanical refactors.682When an automated test would be brittle or have limited long-term value,683a manual testing guide in the commit message or PR description is an684acceptable alternative.686### Commit Structure for Tests688Test placement depends on existing coverage and the type of change:690* When existing tests already cover the behavior being changed, update them in691the same commit as the change. The diff records the old and new expectations692together and shows the change was intentional.693* For a simple feature or bug fix without existing coverage, the change and its694test can often be in the same commit.695* For a non-trivial refactor, if the relevant invariant is not already covered696by automated tests, first add that coverage in a separate test commit. The697refactor commit should not need to update test expectations.698* For a non-trivial change to existing behavior without coverage, consider699adding a preceding commit with a [characterization test](https://en.wikipedia.org/wiki/Characterization_test)700to document the current behavior. Mark assertions whose expected values will701change with `TODO` comments so they are not mistaken for intended behavior.702Remove the comments when updating those assertions in the behavior-changing703commit.705## Locking/mutex usage notes707The code is multi-threaded and uses mutexes and the708`LOCK` and `TRY_LOCK` macros to protect data structures.710Deadlocks due to inconsistent lock ordering (thread 1 locks `cs_main` and then711`cs_wallet`, while thread 2 locks them in the opposite order: result, deadlock712as each waits for the other to release its lock) are a problem. Compile with713`-DDEBUG_LOCKORDER` (or use `-DCMAKE_BUILD_TYPE=Debug`) to get lock order inconsistencies714reported in the `debug.log` file.716Re-architecting the core code so there are better-defined interfaces717between the various components is a goal, with any necessary locking718done by the components (e.g. see the self-contained `FillableSigningProvider` class719and its `cs_KeyStore` lock for example).721## Threads723- [Main thread (`bitcoind`)](https://doxygen.bitcoincore.org/bitcoind_8cpp.html#main)724: Started from `main()` in `bitcoind.cpp`. Responsible for starting up and725shutting down the application.727- [Init load (`b-initload`)](https://doxygen.bitcoincore.org/init_8cpp.html#initload)728: Performs various loading tasks that are part of init but shouldn't block the node from being started: external block import,729reindex, reindex-chainstate, main chain activation, spawn indexes background sync threads and mempool load.731- [CCheckQueue::Loop (`b-scriptch.xx`)](https://doxygen.bitcoincore.org/class_c_check_queue.html#checkqueue)732: Parallel script validation threads for transactions in blocks.734- [ThreadHTTP (`b-http`)](https://doxygen.bitcoincore.org/httpserver_8cpp.html#http)735: Thread to listen for RPC and REST connections.737- [HTTP worker threads (`b-http.xx`)](https://doxygen.bitcoincore.org/httpserver_8cpp.html#http_pool)738: Threads to service RPC and REST requests.740- [Indexer threads (`b-txidx`, `b-blkfltbscidx`, `b-coinstatsidx`, `b-txospenderidx`)](https://doxygen.bitcoincore.org/class_base_index.html#index_sync)741: One thread per indexer.743- [SchedulerThread (`b-scheduler`)](https://doxygen.bitcoincore.org/class_c_scheduler.html#scheduler)744: Does asynchronous background tasks like dumping wallet contents, dumping745addrman and running asynchronous validationinterface callbacks.747- [TorControlThread (`b-torcontrol`)](https://doxygen.bitcoincore.org/class_tor_controller.html#torcontrol)748: Thread for tor connections.750- Net threads:
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.