+ """
+ for name, speedup in speedups.items():
+ # Skip instrumented runs in speedup summary
+ if name.lower().endswith("-instrumented"):
+ continue
+
+ color_class = ""
+ if speedup > 0:
+ color_class = "text-green-600"
+ elif speedup < 0:
+ color_class = "text-red-600"
+
+ sign = "+" if speedup > 0 else ""
+ speedup_rows += f"""
+
+
{name}
+
{sign}{speedup}%
+
+ """
+
+ # Generate graphs section
+ graphs_section = self._generate_graphs_section(runs, input_dir, output_dir)
+
+ return RUN_REPORT_TEMPLATE.format(
+ title=title,
+ run_data_rows=run_data_rows,
+ speedup_rows=speedup_rows,
+ graphs_section=graphs_section,
+ )
+
+ def _linkify_commit(self, command: str) -> str:
+ """Convert commit hashes in command to links."""
+
+ def replace_commit(match):
+ commit = match.group(1)
+ short_commit = commit[:8] if len(commit) > 8 else commit
+ return f'({short_commit})'
+
+ return re.sub(r"\(([a-f0-9]{7,40})\)", replace_commit, command)
+
+ def _generate_graphs_section(
+ self,
+ runs: list[BenchmarkRun],
+ input_dir: Path,
+ output_dir: Path,
+ ) -> str:
+ """Generate the flamegraphs and plots section."""
+ graphs_html = ""
+
+ for run in runs:
+ # Use the command/name directly (e.g., "base", "head")
+ name = run.command
+ network = run.network
+
+ # Check for flamegraph - try both with and without network prefix
+ # Network-prefixed: {network}-{name}-flamegraph.svg (for multi-network reports)
+ # Non-prefixed: {name}-flamegraph.svg (for single-network reports)
+ flamegraph_name = None
+ flamegraph_path = None
+
+ network_prefixed = f"{network}-{name}-flamegraph.svg"
+ non_prefixed = f"{name}-flamegraph.svg"
+
+ if (output_dir / network_prefixed).exists():
+ flamegraph_name = network_prefixed
+ flamegraph_path = output_dir / network_prefixed
+ elif (input_dir / non_prefixed).exists():
+ flamegraph_name = non_prefixed
+ flamegraph_path = input_dir / non_prefixed
+
+ # Check for plots - try both network-prefixed and non-prefixed directories
+ plot_files = []
+ plots_dir = None
+
+ network_plots_dir = output_dir / f"{network}-plots"
+ regular_plots_dir = input_dir / "plots"
+
+ if network_plots_dir.exists():
+ plots_dir = network_plots_dir
+ plot_files = [
+ p.name
+ for p in plots_dir.iterdir()
+ if p.name.startswith(f"{name}-") and p.suffix == ".png"
+ ]
+ elif regular_plots_dir.exists():
+ plots_dir = regular_plots_dir
+ plot_files = [
+ p.name
+ for p in plots_dir.iterdir()
+ if p.name.startswith(f"{name}-") and p.suffix == ".png"
+ ]
+
+ if not flamegraph_path and not plot_files:
+ continue
+
+ # Build display label
+ display_label = f"{network} - {name}" if network != "default" else name
+
+ graphs_html += f"""
+
+
{display_label}
+ """
+
+ if flamegraph_path:
+ graphs_html += f"""
+
+ """
+
+ if plot_files and plots_dir:
+ # Determine the relative path for plots
+ plots_rel_path = plots_dir.name
+ for plot in sorted(plot_files):
+ graphs_html += f"""
+
+
+
+ """
+
+ graphs_html += "
"
+
+ if graphs_html:
+ return f"""
+
Flamegraphs and Plots
+ {graphs_html}
+ """
+
+ return ""
+
+ def _copy_artifacts(self, input_dir: Path, output_dir: Path) -> None:
+ """Copy flamegraphs and plots to output directory."""
+ # Skip if input and output are the same directory
+ if input_dir.resolve() == output_dir.resolve():
+ logger.debug("Input and output are the same directory, skipping copy")
+ return
+
+ # Copy flamegraphs
+ for svg in input_dir.glob("*-flamegraph.svg"):
+ dest = output_dir / svg.name
+ shutil.copy2(svg, dest)
+ logger.debug(f"Copied {svg.name}")
+
+ # Copy plots directory
+ plots_dir = input_dir / "plots"
+ if plots_dir.exists():
+ dest_plots = output_dir / "plots"
+ if dest_plots.exists():
+ shutil.rmtree(dest_plots)
+ shutil.copytree(plots_dir, dest_plots)
+ logger.debug("Copied plots directory")
+
+
+class ReportPhase:
+ """Generate reports from benchmark results."""
+
+ def __init__(
+ self, repo_url: str = "https://github.com/bitcoin-dev-tools/benchcoin"
+ ):
+ self.generator = ReportGenerator(repo_url)
+
+ def run(
+ self,
+ input_dir: Path,
+ output_dir: Path,
+ title: str = "Benchmark Results",
+ ) -> ReportResult:
+ """Generate report from benchmark artifacts.
+
+ Args:
+ input_dir: Directory containing results.json and artifacts
+ output_dir: Where to write the HTML report
+ title: Title for the report
+
+ Returns:
+ ReportResult with paths and speedup data
+ """
+ return self.generator.generate(input_dir, output_dir, title)
+
+ def run_multi_network(
+ self,
+ network_dirs: dict[str, Path],
+ output_dir: Path,
+ title: str = "Benchmark Results",
+ pr_number: str | None = None,
+ run_id: str | None = None,
+ ) -> ReportResult:
+ """Generate report from multiple network benchmark results.
+
+ Args:
+ network_dirs: Dict mapping network name to directory containing results.json
+ output_dir: Where to write the HTML report
+ title: Title for the report
+ pr_number: PR number (for CI reports)
+ run_id: Run ID (for CI reports)
+
+ Returns:
+ ReportResult with paths and speedup data
+ """
+ return self.generator.generate_multi_network(
+ network_dirs, output_dir, title, pr_number, run_id
+ )
+
+ def update_index(self, results_dir: Path, output_file: Path) -> None:
+ """Update the main index.html listing all results.
+
+ Args:
+ results_dir: Directory containing pr-* subdirectories
+ output_file: Where to write index.html
+ """
+ self.generator.generate_index(results_dir, output_file)
diff --git a/bench/utils.py b/bench/utils.py
new file mode 100644
index 000000000000..df454cf0644e
--- /dev/null
+++ b/bench/utils.py
@@ -0,0 +1,105 @@
+"""Utility functions for git operations."""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class GitState:
+ """Saved git state for restoration after operations."""
+
+ def __init__(self, repo_path: Path | None = None):
+ self.repo_path = repo_path or Path.cwd()
+ self.original_branch: str | None = None
+ self.original_commit: str | None = None
+ self.was_detached: bool = False
+
+ def save(self) -> None:
+ """Save current git state."""
+ # Check if we're on a branch or detached HEAD
+ result = subprocess.run(
+ ["git", "symbolic-ref", "--short", "HEAD"],
+ capture_output=True,
+ text=True,
+ cwd=self.repo_path,
+ )
+
+ if result.returncode == 0:
+ self.original_branch = result.stdout.strip()
+ self.was_detached = False
+ else:
+ # Detached HEAD - save commit hash
+ result = subprocess.run(
+ ["git", "rev-parse", "HEAD"],
+ capture_output=True,
+ text=True,
+ check=True,
+ cwd=self.repo_path,
+ )
+ self.original_commit = result.stdout.strip()
+ self.was_detached = True
+
+ logger.debug(
+ f"Saved git state: branch={self.original_branch}, "
+ f"commit={self.original_commit}, detached={self.was_detached}"
+ )
+
+ def restore(self) -> None:
+ """Restore saved git state."""
+ if self.original_branch:
+ logger.debug(f"Restoring branch: {self.original_branch}")
+ subprocess.run(
+ ["git", "checkout", self.original_branch],
+ check=True,
+ cwd=self.repo_path,
+ )
+ elif self.original_commit:
+ logger.debug(f"Restoring detached HEAD: {self.original_commit}")
+ subprocess.run(
+ ["git", "checkout", self.original_commit],
+ check=True,
+ cwd=self.repo_path,
+ )
+
+
+class GitError(Exception):
+ """Git operation failed."""
+
+ pass
+
+
+def git_checkout(commit: str, repo_path: Path | None = None) -> None:
+ """Checkout a specific commit."""
+ repo_path = repo_path or Path.cwd()
+ logger.info(f"Checking out {commit[:12]}")
+
+ result = subprocess.run(
+ ["git", "checkout", commit],
+ cwd=repo_path,
+ capture_output=True,
+ text=True,
+ )
+
+ if result.returncode != 0:
+ raise GitError(f"Failed to checkout {commit}: {result.stderr}")
+
+
+def git_rev_parse(ref: str, repo_path: Path | None = None) -> str:
+ """Resolve a git reference to a full commit hash."""
+ repo_path = repo_path or Path.cwd()
+
+ result = subprocess.run(
+ ["git", "rev-parse", ref],
+ cwd=repo_path,
+ capture_output=True,
+ text=True,
+ )
+
+ if result.returncode != 0:
+ raise GitError(f"Failed to resolve {ref}: {result.stderr}")
+
+ return result.stdout.strip()
diff --git a/doc/benchcoin.md b/doc/benchcoin.md
new file mode 100644
index 000000000000..0b4159256c95
--- /dev/null
+++ b/doc/benchcoin.md
@@ -0,0 +1,127 @@
+# benchcoin
+
+A Bitcoin Core benchmarking fork
+
+This repository is a fork of Bitcoin Core that performs automated IBD benchmarking.
+It allows you to measure and compare the performance impact of certain types of changes to Bitcoin Core's codebase on a longer-running IBD benchmark, in a (pretty) reproducible fashion.
+
+## Features
+
+- Automated IBD benchmarking on pull requests
+- Multiple configurations:
+ - Mainnet with default cache
+ - Mainnet with large cache
+- Performance visualizations including:
+ - Flamegraphs for CPU profiling
+ - Time series plots of various metrics
+ - Compare `base` (bitcoin/bitcoin:master) and `head` (PR)
+
+## Example Flamegraph
+
+Below is an example flamegraph showing CPU utilization during IBD:
+
+
+
+## How to use it
+
+1. Open a Pull Request against **this repo**
+2. Wait for the bot to comment on your PR after it's finished.
+
+See the [Contributing](#contributing) section for more details.
+
+## How it works
+
+When you open a pull request against this repository:
+
+1. The CI workflow automatically builds both the base and PR versions of bitcoind
+2. Runs IBD benchmarks
+3. Records performance metrics and creates various visualizations
+4. Posts results as a comment on your PR
+
+The benchmarks test three configurations:
+- Mainnet-default: with default (450 MB) dbcache
+ - From a pruned datadir @ height 840,000 to height 855,000
+- Mainnet-large: with 32000 MB dbcache
+ - From a pruned datadir @ height 840,000 to height 855,000
+
+## Benchmark Outputs
+
+For each benchmark run, you'll get a github pages page with:
+
+- Timing comparisons between base and PR versions
+- CPU flamegraphs showing where time is spent
+- Time series plots showing:
+ - Block height vs time
+ - Cache size vs block height
+ - Cache size vs time
+ - Transaction count vs block height
+ - Coins cache size vs time
+ - LevelDB metrics
+ - Memory pool metrics
+
+## Local Development (WIP)
+
+To run benchmarks locally (WIP, and Linux-only due to [shell.nix](../shell.nix) limitations):
+
+1. Make sure you have [Nix package manager](https://nixos.org/download/) installed
+
+2. Setup the Nix development environment:
+```bash
+nix-shell
+```
+
+3. Run a local benchmark:
+```bash
+just run-signet
+```
+
+This will:
+- Create a temporary directory for testing
+- Build both base and PR versions
+- Download the required UTXO snapshot if needed
+- Run the benchmark
+- Generate performance visualizations
+
+## Technical Details
+
+The benchmarking system uses:
+- [Hyperfine](https://github.com/sharkdp/hyperfine) for benchmark timing
+- [Flamegraph](https://github.com/willcl-ark/flamegraph) for CPU profiling
+- [matplotlib](https://matplotlib.org/) for metric visualization
+- [GitHub Actions](https://github.com/features/actions) for CI automation
+
+The system copies over a pruned datadir to speed up IBD to a more interesting height (840k).
+
+### Runner & seed
+
+The CI runner is self-hosted on a Hetzner AX52 running at the bitcoin-dev-tools organsation level.
+It is running NixOS using configuration found in this repo: [nix-github-runner](https://github.com/bitcoin-dev-tools/nix-github-runner) for easier deployment and reproducibility.
+
+The runner host has 16 cores, with one used for system, one for `flamegraph` (i.e. `perf record`) and 14 dedicated to the Bitcoin Core node under test.
+
+The benchmarking peer on the runner is served blocks over the (real) "internet" (it may be LAN as it's within a single Hetzner region) via a single peer to exercise full IBD codepaths. This naturally may introduce some variance, but it was deemed preferable to running another bitcoin core on the same machine.
+
+This seed peer is another Hetzner VPS in the same region, and its configuration can be found here: [nix-seed-node](https://github.com/bitcoin-dev-tools/nix-seed-node)
+
+## Contributing
+
+### Benchmark an existing bitcoin/bitcoin PR
+
+This requires `just` be installed. If you don't have `just` installed you can run the commands in the [justfile](../justfile) manually.
+
+1. Fork this repository (or bitcoin/bitcoin and add this as a remote)
+2. Create a new branch from benchcoin/master
+3. Run: `just pick-pr ` to cherry-pick commits from the PR
+4. Push the branch
+5. Open a pull request **against this repo. NOT bitcoin/bitcoin**
+
+### Benchmark standalone/new changes
+
+1. Fork this repository (or bitcoin/bitcoin and add this as a remote)
+2. Make your changes to Bitcoin Core
+3. Open a pull request **against this repo. NOT bitcoin/bitcoin**
+4. Wait for benchmark results to be posted on your PR here
+
+## License
+
+This project is licensed under the same terms as Bitcoin Core - see the [COPYING](../COPYING) file for details.
diff --git a/doc/flamegraph.svg b/doc/flamegraph.svg
new file mode 100644
index 000000000000..77f05068edd1
--- /dev/null
+++ b/doc/flamegraph.svg
@@ -0,0 +1,491 @@
+
diff --git a/flake.lock b/flake.lock
new file mode 100644
index 000000000000..fc1308c520fa
--- /dev/null
+++ b/flake.lock
@@ -0,0 +1,27 @@
+{
+ "nodes": {
+ "nixpkgs": {
+ "locked": {
+ "lastModified": 1764983851,
+ "narHash": "sha256-y7RPKl/jJ/KAP/VKLMghMgXTlvNIJMHKskl8/Uuar7o=",
+ "owner": "NixOS",
+ "repo": "nixpkgs",
+ "rev": "d9bc5c7dceb30d8d6fafa10aeb6aa8a48c218454",
+ "type": "github"
+ },
+ "original": {
+ "owner": "NixOS",
+ "ref": "nixos-25.11",
+ "repo": "nixpkgs",
+ "type": "github"
+ }
+ },
+ "root": {
+ "inputs": {
+ "nixpkgs": "nixpkgs"
+ }
+ }
+ },
+ "root": "root",
+ "version": 7
+}
diff --git a/flake.nix b/flake.nix
new file mode 100644
index 000000000000..b42180629d1a
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,170 @@
+{
+ description = "bitcoind for benchmarking";
+
+ inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
+
+ outputs =
+ { self, nixpkgs }:
+ let
+ systems = [
+ "x86_64-linux"
+ "aarch64-darwin"
+ ];
+
+ forAllSystems = f: nixpkgs.lib.genAttrs systems (system: f system);
+
+ pkgsFor = system: import nixpkgs { inherit system; };
+
+ mkBitcoinCore =
+ system:
+ let
+ pkgs = pkgsFor system;
+ inherit (pkgs) lib;
+
+ pname = "bitcoin-core";
+ version = self.shortRev or "dirty";
+
+ CFlags = toString [
+ "-O2"
+ "-g"
+ ];
+ CXXFlags = "${CFlags} -fno-omit-frame-pointer";
+
+ nativeBuildInputs = [
+ pkgs.cmake
+ pkgs.ninja
+ pkgs.pkg-config
+ pkgs.python3
+ ];
+
+ buildInputs = [
+ pkgs.boost188.dev
+ pkgs.libevent.dev
+ ];
+
+ cmakeFlags = [
+ "-DBUILD_BENCH=OFF"
+ "-DBUILD_BITCOIN_BIN=OFF"
+ "-DBUILD_CLI=OFF"
+ "-DBUILD_DAEMON=ON"
+ "-DBUILD_FUZZ_BINARY=OFF"
+ "-DBUILD_GUI_TESTS=OFF"
+ "-DBUILD_TESTS=OFF"
+ "-DBUILD_TX=OFF"
+ "-DBUILD_UTIL=OFF"
+ "-DBUILD_WALLET_TOOL=OFF"
+ "-DCMAKE_BUILD_TYPE=RelWithDebInfo"
+ "-DCMAKE_SKIP_RPATH=ON"
+ "-DENABLE_EXTERNAL_SIGNER=OFF"
+ "-DENABLE_IPC=OFF"
+ "-DENABLE_WALLET=OFF"
+ "-DREDUCE_EXPORTS=ON"
+ "-DWITH_ZMQ=OFF"
+ ];
+ in
+ pkgs.stdenv.mkDerivation {
+ inherit
+ pname
+ version
+ nativeBuildInputs
+ buildInputs
+ cmakeFlags
+ ;
+
+ preConfigure = ''
+ cmakeFlagsArray+=(
+ "-DAPPEND_CFLAGS=${CFlags}"
+ "-DAPPEND_CXXFLAGS=${CXXFlags}"
+ "-DAPPEND_LDFLAGS=-Wl,--as-needed -Wl,-O2"
+ )
+ '';
+
+ src = builtins.path {
+ path = ./.;
+ name = "source";
+ };
+
+ env = {
+ CMAKE_GENERATOR = "Ninja";
+ LC_ALL = "C";
+ LIBRARY_PATH = "";
+ CPATH = "";
+ C_INCLUDE_PATH = "";
+ CPLUS_INCLUDE_PATH = "";
+ OBJC_INCLUDE_PATH = "";
+ OBJCPLUS_INCLUDE_PATH = "";
+ };
+
+ dontStrip = true;
+
+ meta = {
+ description = "bitcoind for benchmarking";
+ homepage = "https://bitcoincore.org/";
+ license = lib.licenses.mit;
+ };
+ };
+ in
+ {
+ packages = forAllSystems (system: {
+ default = mkBitcoinCore system;
+ });
+
+ formatter = forAllSystems (system: (pkgsFor system).nixfmt-tree);
+
+ devShells = forAllSystems (
+ system:
+ let
+ pkgs = pkgsFor system;
+ inherit (pkgs) stdenv;
+
+ # Override the default cargo-flamegraph with a custom fork including bitcoin highlighting
+ cargo-flamegraph = pkgs.rustPlatform.buildRustPackage rec {
+ pname = "flamegraph";
+ version = "bitcoin-core";
+
+ src = pkgs.fetchFromGitHub {
+ owner = "willcl-ark";
+ repo = "flamegraph";
+ rev = "bitcoin-core";
+ sha256 = "sha256-tQbr3MYfAiOxeT12V9au5KQK5X5JeGuV6p8GR/Sgen4=";
+ };
+
+ doCheck = false;
+ cargoHash = "sha256-QWPqTyTFSZNJNayNqLmsQSu0rX26XBKfdLROZ9tRjrg=";
+
+ nativeBuildInputs = pkgs.lib.optionals stdenv.hostPlatform.isLinux [ pkgs.makeWrapper ];
+ buildInputs = pkgs.lib.optionals stdenv.hostPlatform.isDarwin [
+ pkgs.darwin.apple_sdk.frameworks.Security
+ ];
+
+ postFixup = pkgs.lib.optionalString stdenv.hostPlatform.isLinux ''
+ wrapProgram $out/bin/cargo-flamegraph \
+ --set-default PERF ${pkgs.perf}/bin/perf
+ wrapProgram $out/bin/flamegraph \
+ --set-default PERF ${pkgs.perf}/bin/perf
+ '';
+ };
+ in
+ {
+ default = pkgs.mkShell {
+ buildInputs = [
+ # Benchmarking
+ cargo-flamegraph
+ pkgs.flamegraph
+ pkgs.hyperfine
+ pkgs.jq
+ pkgs.just
+ pkgs.perf
+ pkgs.perf-tools
+ pkgs.python312
+ pkgs.python312Packages.matplotlib
+ pkgs.util-linux
+
+ # Binary patching
+ pkgs.patchelf
+ ];
+ };
+ }
+ );
+ };
+}
diff --git a/justfile b/justfile
new file mode 100644
index 000000000000..d128c7e8b195
--- /dev/null
+++ b/justfile
@@ -0,0 +1,115 @@
+set shell := ["bash", "-uc"]
+
+default:
+ just --list
+
+# ============================================================================
+# Local benchmarking commands
+# ============================================================================
+
+# Test instrumented run using signet (includes report generation)
+[group('local')]
+test-instrumented base head datadir:
+ nix develop --command python3 bench.py build --skip-existing {{ base }}:base {{ head }}:head
+ nix develop --command python3 bench.py --profile quick run \
+ --chain signet \
+ --instrumented \
+ --datadir {{ datadir }} \
+ base:./binaries/base/bitcoind \
+ head:./binaries/head/bitcoind
+ nix develop --command python3 bench.py report bench-output/ bench-output/
+
+# Test uninstrumented run using signet
+[group('local')]
+test-uninstrumented base head datadir:
+ nix develop --command python3 bench.py build --skip-existing {{ base }}:base {{ head }}:head
+ nix develop --command python3 bench.py --profile quick run \
+ --chain signet \
+ --datadir {{ datadir }} \
+ base:./binaries/base/bitcoind \
+ head:./binaries/head/bitcoind
+
+# Full benchmark with instrumentation (flamegraphs + plots)
+[group('local')]
+instrumented base head datadir:
+ python3 bench.py build {{ base }}:base {{ head }}:head
+ python3 bench.py --profile quick run \
+ --instrumented \
+ --datadir {{ datadir }} \
+ base:./binaries/base/bitcoind \
+ head:./binaries/head/bitcoind
+
+# Just build binaries (useful for incremental testing)
+[group('local')]
+build *commits:
+ python3 bench.py build {{ commits }}
+
+# Run benchmark with pre-built binaries
+[group('local')]
+run datadir *binaries:
+ python3 bench.py run --datadir {{ datadir }} {{ binaries }}
+
+# Generate plots from a debug.log file
+[group('local')]
+analyze commit logfile output_dir="./plots":
+ python3 bench.py analyze {{ commit }} {{ logfile }} --output-dir {{ output_dir }}
+
+# Compare benchmark results
+[group('local')]
+compare *results_files:
+ python3 bench.py compare {{ results_files }}
+
+# Generate HTML report from benchmark results
+[group('local')]
+report input_dir output_dir:
+ python3 bench.py report {{ input_dir }} {{ output_dir }}
+
+# ============================================================================
+# CI commands (called by GitHub Actions)
+# ============================================================================
+
+# Build binaries for CI
+[group('ci')]
+ci-build base_commit head_commit binaries_dir:
+ python3 bench.py build -o {{ binaries_dir }} {{ base_commit }}:base {{ head_commit }}:head
+
+# Run uninstrumented benchmarks for CI
+[group('ci')]
+ci-run datadir tmp_datadir output_dir dbcache binaries_dir:
+ python3 bench.py --profile ci run \
+ --datadir {{ datadir }} \
+ --tmp-datadir {{ tmp_datadir }} \
+ --output-dir {{ output_dir }} \
+ --dbcache {{ dbcache }} \
+ base:{{ binaries_dir }}/base/bitcoind \
+ head:{{ binaries_dir }}/head/bitcoind
+
+# Run instrumented benchmarks for CI
+[group('ci')]
+ci-run-instrumented datadir tmp_datadir output_dir dbcache binaries_dir:
+ python3 bench.py --profile ci run \
+ --instrumented \
+ --datadir {{ datadir }} \
+ --tmp-datadir {{ tmp_datadir }} \
+ --output-dir {{ output_dir }} \
+ --dbcache {{ dbcache }} \
+ base:{{ binaries_dir }}/base/bitcoind \
+ head:{{ binaries_dir }}/head/bitcoind
+
+# ============================================================================
+# Git helpers
+# ============================================================================
+
+# Cherry-pick commits from a Bitcoin Core PR onto this branch
+[group('git')]
+pick-pr pr_number:
+ #!/usr/bin/env bash
+ set -euxo pipefail
+
+ if ! git remote get-url upstream 2>/dev/null | grep -q "bitcoin/bitcoin"; then
+ echo "Error: 'upstream' remote not found or doesn't point to bitcoin/bitcoin"
+ echo "Please add it with: git remote add upstream https://github.com/bitcoin/bitcoin.git"
+ exit 1
+ fi
+
+ git fetch upstream pull/{{ pr_number }}/head:bench-{{ pr_number }} && git cherry-pick $(git rev-list --reverse bench-{{ pr_number }} --not upstream/master)
diff --git a/src/bench/CMakeLists.txt b/src/bench/CMakeLists.txt
index e0e03b1df7cc..c82f48b6af0a 100644
--- a/src/bench/CMakeLists.txt
+++ b/src/bench/CMakeLists.txt
@@ -19,6 +19,7 @@ add_executable(bench_bitcoin
checkblockindex.cpp
checkqueue.cpp
cluster_linearize.cpp
+ coinsviewcacheasync.cpp
connectblock.cpp
crypto_hash.cpp
descriptors.cpp
diff --git a/src/bench/coinsviewcacheasync.cpp b/src/bench/coinsviewcacheasync.cpp
new file mode 100644
index 000000000000..9d8fdcf703c5
--- /dev/null
+++ b/src/bench/coinsviewcacheasync.cpp
@@ -0,0 +1,53 @@
+// Copyright (c) The Bitcoin Core developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+#include
+#include
+#include
+
+static void CoinsViewCacheAsyncBenchmark(benchmark::Bench& bench)
+{
+ CBlock block;
+ DataStream{benchmark::data::block413567} >> TX_WITH_WITNESS(block);
+ const auto testing_setup{MakeNoLogFileContext(ChainType::MAIN, { .coins_db_in_memory = false })};
+ Chainstate& chainstate{testing_setup->m_node.chainman->ActiveChainstate()};
+ auto& coins_tip{WITH_LOCK(testing_setup->m_node.chainman->GetMutex(), return chainstate.CoinsTip();)};
+
+ for (const auto& tx : block.vtx | std::views::drop(1)) {
+ for (const auto& in : tx->vin) {
+ Coin coin{};
+ coin.out.nValue = 1;
+ coins_tip.EmplaceCoinInternalDANGER(COutPoint{in.prevout}, std::move(coin));
+ }
+ }
+ chainstate.ForceFlushStateToDisk();
+ const auto& coins_db{WITH_LOCK(testing_setup->m_node.chainman->GetMutex(), return chainstate.CoinsDB();)};
+ CoinsViewCacheAsync async_cache{coins_tip, coins_db};
+
+ bench.run([&] {
+ async_cache.StartFetching(block);
+ for (const auto& tx : block.vtx | std::views::drop(1)) {
+ for (const auto& in : tx->vin) {
+ const auto have{async_cache.HaveCoin(in.prevout)};
+ assert(have);
+ }
+ }
+ async_cache.Reset();
+ });
+}
+
+BENCHMARK(CoinsViewCacheAsyncBenchmark, benchmark::PriorityLevel::HIGH);
diff --git a/src/coins.cpp b/src/coins.cpp
index 554a3ebe962b..d7bd45fb28a6 100644
--- a/src/coins.cpp
+++ b/src/coins.cpp
@@ -173,6 +173,12 @@ bool CCoinsViewCache::HaveCoinInCache(const COutPoint &outpoint) const {
return (it != cacheCoins.end() && !it->second.coin.IsSpent());
}
+std::optional CCoinsViewCache::GetPossiblySpentCoinFromCache(const COutPoint& outpoint) const noexcept
+{
+ if (auto it{cacheCoins.find(outpoint)}; it != cacheCoins.end()) return it->second.coin;
+ return std::nullopt;
+}
+
uint256 CCoinsViewCache::GetBestBlock() const {
if (hashBlock.IsNull())
hashBlock = base->GetBestBlock();
@@ -185,18 +191,16 @@ void CCoinsViewCache::SetBestBlock(const uint256 &hashBlockIn) {
bool CCoinsViewCache::BatchWrite(CoinsViewCacheCursor& cursor, const uint256 &hashBlockIn) {
for (auto it{cursor.Begin()}; it != cursor.End(); it = cursor.NextAndMaybeErase(*it)) {
- // Ignore non-dirty entries (optimization).
- if (!it->second.IsDirty()) {
+ if (!it->second.IsDirty()) { // TODO a cursor can only contain dirty entries
continue;
}
- CCoinsMap::iterator itUs = cacheCoins.find(it->first);
- if (itUs == cacheCoins.end()) {
- // The parent cache does not have an entry, while the child cache does.
- // We can ignore it if it's both spent and FRESH in the child
- if (!(it->second.IsFresh() && it->second.coin.IsSpent())) {
- // Create the coin in the parent cache, move the data up
- // and mark it as dirty.
- itUs = cacheCoins.try_emplace(it->first).first;
+ auto [itUs, inserted]{cacheCoins.try_emplace(it->first)};
+ if (inserted) {
+ if (it->second.IsFresh() && it->second.coin.IsSpent()) {
+ cacheCoins.erase(itUs); // TODO fresh coins should have been removed at spend
+ } else {
+ // The parent cache does not have an entry, while the child cache does.
+ // Move the data up and mark it as dirty.
CCoinsCacheEntry& entry{itUs->second};
assert(entry.coin.DynamicMemoryUsage() == 0);
if (cursor.WillErase(*it)) {
diff --git a/src/coins.h b/src/coins.h
index 2fcc764a3fdf..9ae602165dcc 100644
--- a/src/coins.h
+++ b/src/coins.h
@@ -401,6 +401,14 @@ class CCoinsViewCache : public CCoinsViewBacked
*/
bool HaveCoinInCache(const COutPoint &outpoint) const;
+ /**
+ * Retrieve the coin from the cache even if it is spent, without calling
+ * the backing CCoinsView if no coin exists.
+ * Used in CoinsViewCacheAsync to make sure we do not add a coin from the backing
+ * view when it is spent in the cache but not yet flushed to the parent.
+ */
+ std::optional GetPossiblySpentCoinFromCache(const COutPoint& outpoint) const noexcept;
+
/**
* Return a reference to Coin in the cache, or coinEmpty if not found. This is
* more efficient than GetCoin.
@@ -441,7 +449,7 @@ class CCoinsViewCache : public CCoinsViewBacked
* to be forgotten.
* If false is returned, the state of this cache (and its backing view) will be undefined.
*/
- bool Flush();
+ virtual bool Flush();
/**
* Push the modifications applied to this cache to its base while retaining
@@ -482,7 +490,7 @@ class CCoinsViewCache : public CCoinsViewBacked
* @note this is marked const, but may actually append to `cacheCoins`, increasing
* memory usage.
*/
- CCoinsMap::iterator FetchCoin(const COutPoint &outpoint) const;
+ virtual CCoinsMap::iterator FetchCoin(const COutPoint &outpoint) const;
};
//! Utility function to add all of a transaction's outputs to a cache.
diff --git a/src/coinsviewcacheasync.h b/src/coinsviewcacheasync.h
new file mode 100644
index 000000000000..7114258060e2
--- /dev/null
+++ b/src/coinsviewcacheasync.h
@@ -0,0 +1,247 @@
+// Copyright (c) The Bitcoin Core developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#ifndef BITCOIN_COINSVIEWCACHEASYNC_H
+#define BITCOIN_COINSVIEWCACHEASYNC_H
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+static constexpr int32_t WORKER_THREADS{4};
+
+/**
+ * CCoinsViewCache subclass that asynchronously fetches block inputs in parallel.
+ * Only used in ConnectBlock to pass as an ephemeral view that can be reset if the block is invalid.
+ * It provides the same interface as CCoinsViewCache, overriding the FetchCoin private method and Flush.
+ * It adds an additional StartFetching method to provide the block, and Reset to reset the state if Flush is not called.
+ *
+ * The cache spawns a fixed set of worker threads that fetch Coins for each input in a block.
+ * When FetchCoin() is called, the main thread waits for the corresponding coin to be fetched and returns it.
+ * While waiting, the main thread will also fetch coins to maximize parallelism.
+ *
+ * Worker threads are synchronized with the main thread using a barrier, which is used at the beginning of fetching to
+ * start the workers and at the end to ensure all workers have finished before the next block is started.
+ */
+class CoinsViewCacheAsync : public CCoinsViewCache
+{
+private:
+ //! The latest input not yet being fetched. Workers atomically increment this when fetching.
+ mutable std::atomic_uint32_t m_input_head{0};
+ //! The latest input not yet accessed by a consumer. Only the main thread increments this.
+ mutable uint32_t m_input_tail{0};
+
+ //! The inputs of the block which is being fetched.
+ struct InputToFetch {
+ //! Workers set this after setting the coin. The main thread tests this before reading the coin.
+ std::atomic_flag ready{};
+ //! The outpoint of the input to fetch;
+ const COutPoint& outpoint;
+ //! The coin that workers will fetch and main thread will insert into cache.
+ std::optional coin{std::nullopt};
+
+ /**
+ * We only move when m_inputs reallocates during setup.
+ * We never move after work begins, so we don't have to copy other members.
+ */
+ InputToFetch(InputToFetch&& other) noexcept : outpoint{other.outpoint} {}
+ explicit InputToFetch(const COutPoint& o LIFETIMEBOUND) noexcept : outpoint{o} {}
+ };
+ mutable std::vector m_inputs{};
+
+ /**
+ * The first 8 bytes of txids of all txs in the block being fetched. This is used to filter out inputs that
+ * are created earlier in the same block, since they will not be in the db or the cache.
+ * Using only the first 8 bytes is a performance improvement, versus storing the entire 32 bytes. In case of a
+ * collision of an input being spent having the same first 8 bytes as a txid of a tx elsewhere in the block,
+ * the input will not be fetched in the background. The input will still be fetched later on the main thread.
+ * Using a sorted vector and binary search lookups is a performance improvement. It is faster than
+ * using std::unordered_set with salted hash or std::set.
+ */
+ std::vector m_txids{};
+
+ //! DB coins view to fetch from.
+ const CCoinsView& m_db;
+
+ /**
+ * Similar to CCoinsViewCache::GetCoin, but it does not mutate internally.
+ * Therefore safe to call from any thread once inside the barrier.
+ */
+ std::optional GetCoinWithoutMutating(const COutPoint& outpoint) const
+ {
+ if (auto coin{static_cast(base)->GetPossiblySpentCoinFromCache(outpoint)}) {
+ if (!coin->IsSpent()) [[likely]] return coin;
+ return std::nullopt;
+ }
+ return m_db.GetCoin(outpoint);
+ }
+
+ /**
+ * Claim and fetch the next input in the queue. Safe to call from any thread once inside the barrier.
+ *
+ * @return true if there are more inputs in the queue to fetch
+ * @return false if there are no more inputs in the queue to fetch
+ */
+ bool ProcessInputInBackground() const noexcept
+ {
+ const auto i{m_input_head.fetch_add(1, std::memory_order_relaxed)};
+ if (i >= m_inputs.size()) [[unlikely]] return false;
+
+ auto& input{m_inputs[i]};
+ // Inputs spending a coin from a tx earlier in the block won't be in the cache or db
+ if (std::ranges::binary_search(m_txids, input.outpoint.hash.ToUint256().GetUint64(0))) {
+ // We can use relaxed ordering here since we don't write the coin.
+ input.ready.test_and_set(std::memory_order_relaxed);
+ input.ready.notify_one();
+ return true;
+ }
+
+ if (auto coin{GetCoinWithoutMutating(input.outpoint)}) [[likely]] input.coin.emplace(std::move(*coin));
+ // We need release here, so writing coin in the line above happens before the main thread acquires.
+ input.ready.test_and_set(std::memory_order_release);
+ input.ready.notify_one();
+ return true;
+ }
+
+ //! Get the index in m_inputs for the given outpoint. Advances m_input_tail if found.
+ std::optional GetInputIndex(const COutPoint& outpoint) const noexcept
+ {
+ // This assumes ConnectBlock accesses all inputs in the same order as they are added to m_inputs
+ // in StartFetching. Some outpoints are not accessed because they are created by the block, so we scan until we
+ // come across the requested input. The input will be cached after access, so we can advance the tail so
+ // future accesses won't have to scan previously accessed inputs.
+ for (const auto i : std::views::iota(m_input_tail, m_inputs.size())) [[likely]] {
+ if (m_inputs[i].outpoint == outpoint) {
+ m_input_tail = i + 1;
+ return i;
+ }
+ }
+ return std::nullopt;
+ }
+
+ CCoinsMap::iterator FetchCoin(const COutPoint& outpoint) const override
+ {
+ const auto& [ret, inserted]{cacheCoins.try_emplace(outpoint)};
+ if (!inserted) return ret;
+
+ if (const auto i{GetInputIndex(outpoint)}) [[likely]] {
+ auto& input{m_inputs[*i]};
+ // Check if the coin is ready to be read. We need to acquire to match the worker thread's release.
+ while (!input.ready.test(std::memory_order_acquire)) {
+ // Work instead of waiting if the coin is not ready
+ if (!ProcessInputInBackground()) {
+ // No more work, just wait
+ input.ready.wait(/*old=*/false, std::memory_order_acquire);
+ break;
+ }
+ }
+ if (input.coin) [[likely]] ret->second.coin = std::move(*input.coin);
+ }
+
+ if (ret->second.coin.IsSpent()) [[unlikely]] {
+ // We will only get in here for BIP30 checks, txid collisions, or a block with missing or spent inputs.
+ if (auto coin{GetCoinWithoutMutating(outpoint)}) {
+ ret->second.coin = std::move(*coin);
+ } else {
+ cacheCoins.erase(ret);
+ return cacheCoins.end();
+ }
+ }
+
+ cachedCoinsUsage += ret->second.coin.DynamicMemoryUsage();
+ return ret;
+ }
+
+ std::vector m_worker_threads{};
+ std::barrier<> m_barrier;
+
+ //! Stop all worker threads.
+ void StopFetching() noexcept
+ {
+ if (m_inputs.empty()) return;
+ // Skip fetching the rest of the inputs by moving the head to the end.
+ m_input_head.store(m_inputs.size(), std::memory_order_relaxed);
+ // Wait for all threads to stop.
+ m_barrier.arrive_and_wait();
+ m_inputs.clear();
+ }
+
+public:
+ //! Start fetching all block inputs in parallel.
+ void StartFetching(const CBlock& block) noexcept
+ {
+ // Loop through the inputs of the block and set them in the queue. Also construct the set of txids to filter.
+ for (const auto& tx : block.vtx | std::views::drop(1)) [[likely]] {
+ for (const auto& input : tx->vin) [[likely]] m_inputs.emplace_back(input.prevout);
+ m_txids.emplace_back(tx->GetHash().ToUint256().GetUint64(0));
+ }
+ // Don't start threads if there's nothing to fetch.
+ if (m_inputs.empty()) [[unlikely]] return;
+ // Sort txids so we can do binary search lookups.
+ std::ranges::sort(m_txids);
+ // Start workers by entering the barrier.
+ m_barrier.arrive_and_wait();
+ }
+
+ //! Stop fetching and reset state. Must be called before block is destroyed.
+ void Reset() noexcept
+ {
+ StopFetching();
+ m_input_head.store(0, std::memory_order_relaxed);
+ m_input_tail = 0;
+ m_txids.clear();
+ cacheCoins.clear();
+ cachedCoinsUsage = 0;
+ hashBlock = uint256::ZERO;
+ }
+
+ bool Flush() override
+ {
+ // We need to stop workers from accessing base before we mutate it.
+ StopFetching();
+ auto cursor{CoinsViewCacheCursor(m_sentinel, cacheCoins, /*will_erase=*/true)};
+ const auto ret{base->BatchWrite(cursor, hashBlock)};
+ Reset();
+ return ret;
+ }
+
+ explicit CoinsViewCacheAsync(CCoinsViewCache& cache, const CCoinsView& db,
+ int32_t num_workers = WORKER_THREADS) noexcept
+ : CCoinsViewCache{&cache}, m_db{db}, m_barrier{num_workers + 1}
+ {
+ for (const auto n : std::views::iota(0, num_workers)) {
+ m_worker_threads.emplace_back([this, n] {
+ util::ThreadRename(strprintf("inputfetch.%i", n));
+ while (true) {
+ m_barrier.arrive_and_wait();
+ while (ProcessInputInBackground()) [[likely]] {}
+ if (m_inputs.empty()) [[unlikely]] return;
+ m_barrier.arrive_and_wait();
+ }
+ });
+ }
+ }
+
+ ~CoinsViewCacheAsync() override
+ {
+ m_barrier.arrive_and_drop();
+ for (auto& t : m_worker_threads) t.join();
+ }
+};
+
+#endif // BITCOIN_COINSVIEWCACHEASYNC_H
diff --git a/src/test/CMakeLists.txt b/src/test/CMakeLists.txt
index 83cb989aa9b1..96c95cc4571c 100644
--- a/src/test/CMakeLists.txt
+++ b/src/test/CMakeLists.txt
@@ -32,6 +32,7 @@ add_executable(test_bitcoin
cluster_linearize_tests.cpp
coins_tests.cpp
coinscachepair_tests.cpp
+ coinsviewcacheasync_tests.cpp
coinstatsindex_tests.cpp
common_url_tests.cpp
compress_tests.cpp
diff --git a/src/test/coinsviewcacheasync_tests.cpp b/src/test/coinsviewcacheasync_tests.cpp
new file mode 100644
index 000000000000..54425647a085
--- /dev/null
+++ b/src/test/coinsviewcacheasync_tests.cpp
@@ -0,0 +1,221 @@
+// Copyright (c) The Bitcoin Core developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+#include
+
+#include
+#include
+#include
+#include
+
+BOOST_AUTO_TEST_SUITE(coinsviewcacheasync_tests)
+
+struct NoAccessCoinsView : CCoinsView {
+ std::optional GetCoin(const COutPoint&) const override { abort(); }
+};
+
+static CBlock CreateBlock() noexcept
+{
+ static constexpr auto NUM_TXS{100};
+ CBlock block;
+ CMutableTransaction coinbase;
+ coinbase.vin.emplace_back();
+ block.vtx.push_back(MakeTransactionRef(coinbase));
+
+ Txid prevhash{Txid::FromUint256(uint256{1})};
+
+ for (const auto i : std::views::iota(1, NUM_TXS)) {
+ CMutableTransaction tx;
+ Txid txid;
+ if (i % 3 == 0) {
+ // External input
+ txid = Txid::FromUint256(uint256(i));
+ } else if (i % 3 == 1) {
+ // Internal spend (prev tx)
+ txid = prevhash;
+ } else {
+ // Test shortid collisions (looks internal, but is external)
+ uint256 u{};
+ std::memcpy(u.begin(), prevhash.ToUint256().begin(), 8);
+ txid = Txid::FromUint256(u);
+ }
+ tx.vin.emplace_back(txid, 0);
+ prevhash = tx.GetHash();
+ block.vtx.push_back(MakeTransactionRef(tx));
+ }
+
+ return block;
+}
+
+void PopulateView(const CBlock& block, CCoinsView& view, bool spent = false)
+{
+ CCoinsViewCache cache{&view};
+ cache.SetBestBlock(uint256::ONE);
+
+ std::unordered_set txids{};
+ txids.reserve(block.vtx.size() - 1);
+ for (const auto& tx : block.vtx | std::views::drop(1)) {
+ for (const auto& in : tx->vin) {
+ if (!txids.contains(in.prevout.hash)) {
+ Coin coin{};
+ if (!spent) coin.out.nValue = 1;
+ cache.EmplaceCoinInternalDANGER(COutPoint{in.prevout}, std::move(coin));
+ }
+ }
+ txids.emplace(tx->GetHash());
+ }
+
+ cache.Flush();
+}
+
+void CheckCache(const CBlock& block, const CCoinsViewCache& cache)
+{
+ uint32_t counter{0};
+ std::unordered_set txids{};
+ txids.reserve(block.vtx.size() - 1);
+
+ for (const auto& tx : block.vtx) {
+ if (tx->IsCoinBase()) {
+ BOOST_CHECK(!cache.GetPossiblySpentCoinFromCache(tx->vin[0].prevout));
+ } else {
+ for (const auto& in : tx->vin) {
+ const auto& outpoint{in.prevout};
+ const auto& first{cache.AccessCoin(outpoint)};
+ const auto& second{cache.AccessCoin(outpoint)};
+ BOOST_CHECK_EQUAL(&first, &second);
+ const auto should_have{!txids.contains(outpoint.hash)};
+ if (should_have) ++counter;
+ const auto have{cache.GetPossiblySpentCoinFromCache(outpoint)};
+ BOOST_CHECK_EQUAL(should_have, !!have);
+ }
+ txids.emplace(tx->GetHash());
+ }
+ }
+ BOOST_CHECK_EQUAL(cache.GetCacheSize(), counter);
+}
+
+
+BOOST_AUTO_TEST_CASE(fetch_inputs_from_db)
+{
+ const auto block{CreateBlock()};
+ CCoinsViewDB db{{.path = "", .cache_bytes = 1_MiB, .memory_only = true}, {}};
+ PopulateView(block, db);
+ NoAccessCoinsView no_access;
+ CCoinsViewCache main_cache{&no_access};
+ CoinsViewCacheAsync view{main_cache, db};
+ for (auto i{0}; i < 3; ++i) {
+ view.StartFetching(block);
+ CheckCache(block, view);
+ view.Reset();
+ }
+}
+
+BOOST_AUTO_TEST_CASE(fetch_inputs_from_cache)
+{
+ const auto block{CreateBlock()};
+ const CCoinsViewDB db{{.path = "", .cache_bytes = 1_MiB, .memory_only = true}, {}};
+ NoAccessCoinsView no_access;
+ CCoinsViewCache main_cache{&no_access};
+ PopulateView(block, main_cache);
+ CoinsViewCacheAsync view{main_cache, db};
+ for (auto i{0}; i < 3; ++i) {
+ view.StartFetching(block);
+ CheckCache(block, view);
+ view.Reset();
+ }
+}
+
+// Test for the case where a block spends coins that are spent in the cache, but
+// the spentness has not been flushed to the db.
+BOOST_AUTO_TEST_CASE(fetch_no_double_spend)
+{
+ const auto block{CreateBlock()};
+ CCoinsViewDB db{{.path = "", .cache_bytes = 1_MiB, .memory_only = true}, {}};
+ PopulateView(block, db);
+ NoAccessCoinsView no_access;
+ CCoinsViewCache main_cache{&no_access};
+ // Add all inputs as spent already in cache
+ PopulateView(block, main_cache, /*spent=*/true);
+ CoinsViewCacheAsync view{main_cache, db};
+ for (auto i{0}; i < 3; ++i) {
+ view.StartFetching(block);
+ for (const auto& tx : block.vtx) {
+ for (const auto& in : tx->vin) {
+ const auto& c{view.AccessCoin(in.prevout)};
+ BOOST_CHECK(c.IsSpent());
+ }
+ }
+ // Coins are not added to the view, even though they exist unspent in the parent db
+ BOOST_CHECK_EQUAL(view.GetCacheSize(), 0);
+ view.Reset();
+ }
+}
+
+BOOST_AUTO_TEST_CASE(fetch_no_inputs)
+{
+ const auto block{CreateBlock()};
+ const CCoinsViewDB db{{.path = "", .cache_bytes = 1_MiB, .memory_only = true}, {}};
+ NoAccessCoinsView no_access;
+ CCoinsViewCache main_cache{&no_access};
+ CoinsViewCacheAsync view{main_cache, db};
+ for (auto i{0}; i < 3; ++i) {
+ view.StartFetching(block);
+ for (const auto& tx : block.vtx) {
+ for (const auto& in : tx->vin) {
+ const auto& c{view.AccessCoin(in.prevout)};
+ BOOST_CHECK(c.IsSpent());
+ }
+ }
+ BOOST_CHECK_EQUAL(view.GetCacheSize(), 0);
+ view.Reset();
+ }
+}
+
+// Test that the main thread can make progress with no workers
+BOOST_AUTO_TEST_CASE(fetch_main_thread)
+{
+ const auto block{CreateBlock()};
+ const CCoinsViewDB db{{.path = "", .cache_bytes = 1_MiB, .memory_only = true}, {}};
+ NoAccessCoinsView no_access;
+ CCoinsViewCache main_cache{&no_access};
+ PopulateView(block, main_cache);
+ CoinsViewCacheAsync view{main_cache, db, /*num_workers=*/0};
+ for (auto i{0}; i < 3; ++i) {
+ view.StartFetching(block);
+ CheckCache(block, view);
+ view.Reset();
+ }
+}
+
+// Access coin that is not a block's input
+BOOST_AUTO_TEST_CASE(access_non_input_coin)
+{
+ const auto block{CreateBlock()};
+ const CCoinsViewDB db{{.path = "", .cache_bytes = 1_MiB, .memory_only = true}, {}};
+ NoAccessCoinsView no_access;
+ CCoinsViewCache main_cache{&no_access};
+ Coin coin{};
+ coin.out.nValue = 1;
+ const COutPoint outpoint{Txid::FromUint256(uint256::ZERO), 0};
+ main_cache.EmplaceCoinInternalDANGER(COutPoint{Txid::FromUint256(uint256::ZERO), 0}, std::move(coin));
+ CoinsViewCacheAsync view{main_cache, db, /*num_workers=*/0};
+ for (auto i{0}; i < 3; ++i) {
+ view.StartFetching(block);
+ const auto& accessed_coin{view.AccessCoin(outpoint)};
+ BOOST_CHECK(!accessed_coin.IsSpent());
+ view.Reset();
+ }
+}
+
+BOOST_AUTO_TEST_SUITE_END()
diff --git a/src/test/fuzz/CMakeLists.txt b/src/test/fuzz/CMakeLists.txt
index 607723b978ae..2bbda8e88efc 100644
--- a/src/test/fuzz/CMakeLists.txt
+++ b/src/test/fuzz/CMakeLists.txt
@@ -27,6 +27,7 @@ add_executable(fuzz
cluster_linearize.cpp
coins_view.cpp
coinscache_sim.cpp
+ coinsviewcacheasync.cpp
connman.cpp
crypto.cpp
crypto_aes256.cpp
diff --git a/src/test/fuzz/coinsviewcacheasync.cpp b/src/test/fuzz/coinsviewcacheasync.cpp
new file mode 100644
index 000000000000..187d0e49d7a5
--- /dev/null
+++ b/src/test/fuzz/coinsviewcacheasync.cpp
@@ -0,0 +1,181 @@
+// Copyright (c) The Bitcoin Core developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+#include
+#include
+#include
+#include