• Major versions of Bitcoin Core are released every 6-8 months. See the Life Cycle documentation for full details.

• When all of the PRs for a release have been merged, Release Candidate 1 (rc1) is tagged. The rc is then tested. If any issues are found, fixes are merged into the branch and a new rc is tagged. This continues until no major issues are found in an rc, and that rc is then considered to be the final release version.

• To ensure that users don’t experience issues with the new software, it’s essential that the rcs are thoroughly tested. This special review club meeting is for people who want to help with that vital review process.

• This Bitcoin Core Release Candidate Testing Guide provides guidance for testing the release candidate.

• The guide is just to get you started on testing, so feel free to read the Release Notes and bring ideas of other things you’d like to test!

Meeting Log

• This PR adds a fuzz harness for testing compact block relay, along with a few test infrastructure changes to improve speed and stability. Earlier review clubs on fuzzing include: #17860, #18521, #21142, #30605.

• The harness simulates P2P network behavior by having three peers send various messages (CMPCTBLOCK, BLOCKTXN, HEADERS, SENDCMPCT, TX) to the test node, triggering its compact block logic.

• The goal is to find bugs and ensure assertions hold. See #33296 for an example of a bug found by this very fuzz test. Nice!

Compact Blocks Protocol Overview

• BIP 152 introduced the compact block relay protocol, which reduces bandwidth and latency when propagating blocks by sending an encoded version of a block under the assumption that most of the transactions are already in our peer’s mempool.

• Compact blocks consist of:
  • A header
  • Short transaction identifiers (6 bytes instead of 32 bytes)
  • Prefilled transactions
    • A vector where each entry is a differentially-encoded uint16_t index and the complete serialized transaction.
    • The current code only prefills the coinbase. However, the protocol allows for the inclusion of other transactions that we might expect our peer is missing. See this TODO.

• The receiving node reconstructs the block using transactions from its mempool. If any transactions are missing, it requests them via a GETBLOCKTXN message.

• There are two modes:
  • low-bandwidth: block sent only after peer requests it via INV/GETDATA
  • high-bandwidth: block sent to peers without request as soon as it is received, even before full validation is completed

Fuzz Testing

• Fuzzing is a testing technique that provides quasi-random inputs to code to discover bugs and unexpected behavior. Fuzzers use feedback like code coverage as a guide for mutation of those inputs, allowing them to explore deeper paths within the target code.

• See our fuzzing docs to start fuzzing with libFuzzer and AFL++.

• Check out this PR’s test coverage (blockencodings.cpp and net_processing.cpp are probably most useful to look at). Walking through a coverage report to see which branches are hit or not hit is a good way to start evaluating a fuzz harness.

• An effective fuzz test should be deterministic, to make bugs reproducible. If you’re able to get the AFL++ fuzzer running, you will see a stability metric. The goal is to get to 100%, perfect determinism! After gathering some inputs, you can also run the fuzz determinism script over the corpus to check for potential sources of instability.

• The faster (more iterations per second) a fuzz harness is, the more quickly it will discover new code paths and potential bugs. You’ll see this metric as exec/s when fuzzing. Any operation that significantly slows down an iteration (like reading from and writing to disk) should be optimized or avoided if possible.

Fun Exercise

• If you get the cmpctblock harness running, revert PR #33296 and see if you can reproduce the crash on this Assume statement.

• Yeah I know, fuzzing is cool.

Questions

1. Did you review the PR? Concept ACK, approach ACK, tested ACK, or NACK? What was your review approach? Were you able to get the fuzz test running?

2. Where in the codebase are the main compact block helpers and processing logic? Name some of the relevant classes and functions. (Hint: nothing like a little search for NetMsgType::CMPCTBLOCK to get you started)

3. The fuzz test sends SENDCMPCT messages with high_bandwidth randomly set. How many high bandwidth peers are allowed and does the fuzz harness test this limit? More generally, why would a peer choose to be high or low bandwidth?

4. Compare -testdatadir and the new -fuzzcopydatadir. Why is the latter useful for performance, and why isn’t a fresh TestingSetup that mines blocks on each iteration acceptable here?

5. Look at create_block in the harness. How many transactions do the generated blocks contain, and where do they come from? What compact block scenarios might be missed with only a few transactions in a block?

6. In commit 254e13c FinalizeHeader is moved to util.h so it can be used by any fuzz test. What is the purpose of this function and why doesn’t it slow down the fuzzer?

7. Commit ed813c4 sorts m_dirty_blockindex by block hash instead of pointer address. What non-determinism does this fix? The author notes this slows production code for no production benefit. Why can’t EnableFuzzDeterminism() be used here? How do you think this non-determinism should be best handled (if not the way the PR currently does)?

8. The harness adds prefilled transactions to a compact block beyond the coinbase. Walk through the index calculations for prefilling transactions at indices 1 and 3 in a 4-transaction block. Do you think this code could be simplified or cleaned up, and if so, what do you suggest?

Meeting Log

Motivation & user story

• Air-gapped (“signing”) machines hold the private keys; an online (“watch-only”) node tracks balances, generates receive addresses, and prepares PSBTs. Today users must manually recreate that watch-only wallet by typing or scripting importdescriptors, copying address labels, etc.
• exportwatchonlywallet provides a single-step RPC that produces a wallet file containing:
  • All public descriptors (& caches when needed)
  • Address book entries, receive-request metadata, and “avoid-reuse” markers
  • All wallet TXs (so rescans are unnecessary)
  • Persisted locked-coin state and wallet flags
  • No private keys (wallet is created with WALLET_FLAG_DISABLE_PRIVATE_KEYS)

The result can be moved to any node and loaded with the existing restorewallet RPC.

New building blocks introduced in this PR

Walk-through of the export algorithm (very high level)

1. Pre-flight checks – ensure destination path does not exist; grab a canonical path; hold cs_wallet.
2. Gather descriptor data using ExportDescriptors(false).
3. Instantiate a new wallet DB with the same flags ∪ WALLET_FLAG_DISABLE_PRIVATE_KEYS.
4. Populate the new wallet inside a single batch TX:
   • Add each descriptor as a DescriptorScriptPubKeyMan.
     • If !desc->CanSelfExpand(), copy the source descriptor cache first, so address generation works.
   • Copy active SPKMs / internal flags so it knows which pools to use.
   • Copy persistent locked coins, address-book rows, receive-requests, “previously-spent” markers, nOrderPosNext, and best-block locator (to avoid rescan).
   • Copy every CWalletTx so balances are immediately correct.
5. Backup the new wallet to the requested destination and then delete the temp directory.
6. Return the fully-qualified path in the RPC result.

Behavioural quirks & edge-cases worth reviewing

• Hardened xpub paths – these cannot self-expand; exporter copies the cache so watch-only wallet can derive addresses up to the last used index but cannot extend indefinitely.
• Encrypted source wallets – exporter runs while the wallet is locked because it never reads private keys.
• Avoid-reuse & address-book flags – exporter must preserve both the wallet flag and the special “previously spent” metadata to keep behaviour identical.
• Tx ordering & nOrderPosNext – ensures recreated wallet doesn’t reshuffle history.
• Concurrency – every path that reads mutable wallet state is executed under cs_wallet; temp wallet is manipulated under its own lock and inside a batch DB TX.

Questions

1. Review approach Did you test, concept ACK, approach ACK, or NACK the PR? What aspects did you focus on during review?
2. Descriptor API Why can’t the existing IsRange()/IsSingleType() information tell us whether a descriptor can be expanded on the watch-only side? Explain the logic behind CanSelfExpand() for a) a hardened wpkh(xpub/0h/*) path and b) a pkh(pubkey) descriptor.
3. Cache copying ExportWatchOnlyWallet only copies the descriptor cache if !desc->CanSelfExpand(). What exactly is stored in that cache? How could an incomplete cache affect address derivation on the watch-only wallet?
4. Wallet flags The exporter sets create_flags = GetWalletFlags() | WALLET_FLAG_DISABLE_PRIVATE_KEYS. Why is it important to preserve the original flags (e.g. AVOID_REUSE) instead of clearing everything and starting fresh?
5. Best-block locator Why does the exporter read the locator from the source wallet and write it verbatim into the new wallet instead of letting the new wallet start from block 0?
6. Security / privacy Consider a multisig descriptor wsh(multi(2,xpub1,xpub2)). If one cosigner exports a watch-only wallet and shares it with a third party, what new information does that third party learn compared to just giving them the descriptor strings?
7. Functional test In wallet_exported_watchonly.py, why does the test call wallet.keypoolrefill(100) before checking spendability across the online/offline pair?
8. Alternatives Prior to this PR, users could achieve a watch-only setup via dumpwallet → importwallet or importdescriptors. Compare those approaches with exportwatchonlywallet in terms of UX, completeness, and long-term maintainability.

Meeting Log

• The PR description summarizes the motivations for this change and the new eviction strategy: we must ensure the orphanage is DoS-resistant, but also want to prevent any peer from affecting another peer’s usage of orphanage space.

• The PR does a few things: it virtualizes the TxOrphanage class inherited by TxOrphanageImpl, it implements a new eviction strategy, and it replaces the various TxOrphanage data structure(s) with a single boost::multi_index_container.

• With these changes, we can now guarantee at least 1 maximum size-package worth of orphan resolution per peer at a time. This is tested by the txorphan_protected fuzz test and a few functional tests.

• If most peers are not providing orphans, the unused space allocated to them can be used by peers that need it.

• An earlier version of this PR implemented the new eviction strategy using the existing TxOrphanage data structures. This version makes the PR’s behavior changes clearer. It may also demonstrate why a boost::multi_index_container is the more natural data structure for TxOrphanage, as the original implementation is a bit convoluted. You can find that version of the PR here.

Questions

Concept

1. Did you review the PR? Concept ACK, approach ACK, tested ACK, or NACK? What was your review approach?

2. Why is the current TxOrphanage global maximum size limit of 100 transactions with random eviction problematic? Can you think of a concrete attack scenario that would affect 1-parent-1-child (1p1c) relay?

3. Can you summarize the changes to the eviction algorithm at a high level?

4. Why is it desirable to allow peers to exceed their individual limits while the global limits are not reached?

5. The new algorithm evicts announcements instead of transactions. What is the difference and why does it matter?

6. Why is there an announcement “limit” but a memory “reservation”?

7. How does the per-peer memory usage reservation change as the number of peers increases?

8. How does the per-peer announcement limit change as the number of peers increases? Why is this different from the per-peer memory usage reservation?

9. Why is it ok to remove orphan expiration?

10. Should we also remove EraseForBlock and instead rely on eviction to remove orphans that confirm or conflict with a block? Why or why not?

11. Going back to your attack scenario from an earlier question, how does this PR improve the reliability of 1p1c relay in adversarial environments?

Implementation

1. What is the purpose of reimplementing TxOrphanageImpl using a boost::multi_index_container along with the eviction changes?

2. What is a peer’s “DoS Score” and how is it calculated?

3. The global memory limit scales with the number of peers. Could this create new DoS vectors where an attacker opens many connections to increase the global limit?

4. Is it possible for the orphanage to NeedsTrim() when there is no peer whose “DoS Score” is greater than 1?

5. Is it possible that a peer’s “DoS Score” is greater than 1 but NeedsTrim() returns false?

6. When evicting orphans, why evict non-reconsiderable orphans before reconsiderable ones? What’s the difference between these categories?

7. How does the number of announcements represent a meaningful bound on “computation” in TxOrphanage operations?

8. What is the computational complexity of the LimitOrphans loop? How many heap operations can there be? How many erasures can there be?

9. How can we test (and do tests exist?) that TxOrphanage’s internal data structures are updated correctly, that its DoS limits are correctly enforced, and that the orphans of “honest” peers are protected from eviction?

10. How does the txorphan_protected fuzz harness test that orphans are protected from eviction?

11. The default announcement limit is increased from 100 to 3000. How was this number chosen and what are the tradeoffs?

Meeting Log

• A cluster is a group of transactions where some transactions depend on others, forming parent-child relationships. The simplest cluster is a single transaction, and most clusters consist of just a few transactions. However, there can be more complex configurations that form large directed acyclic graphs (with grandparents, siblings, uncles, etc). The current limit on cluster size is 64 transactions.

• At a high level, cluster linearization is the process of sorting the transactions within a given cluster in a way that respects dependencies (parents before children) while maximizing the effective fee rate when considering “chunks” of this ordered list. The goal is to produce an optimal linearization: an ordering with the best possible sequence of chunk fee rates (fee rate profile). This linearization allows miners to include the most profitable transactions first. (for more in-depth reading, see here)
  • The data structures and algorithms for cluster linearization can be found in cluster_linearize.h.

• The linearization code is complex and therefore relies on fuzz testing to ensure correctness. Using the wide variety of data generated by the fuzzer to build dependency graphs (DepGraph instances) and produce/update linearizations is probably our best bet for finding any subtle bugs or edge cases in the code.

• The cluster_linearize fuzz test includes a few helper classes and functions that are used to compare against the actual implementation. The motivation for this PR is to construct new fuzz targets that are used to make sure these helpers work properly. By having dedicated targets that test the test, we can be even more confident that our cluster linearization code is bug-free. Woo!

• Note: the current cluster linearization algorithm may be replaced by a new and improved spanning-forest linearization (SFL) algorithm in the future. SFL is essentially a drop-in replacement, so while the underlying algorithm changes, it doesn’t change the tests much. It’s outside of the scope of this review club, but you can look at PR 32545 or this delving post if you’re interested.

Exercise

• Try fuzzing the clusterlin_linearize target. You can refer to the fuzzing docs for assistance. Using --preset=libfuzzer-nosan will likely make building easier.

• Now change chunking to simple_chunking at this line and run the target again.

• After a few minutes, you should see a crash. Welcome to fuzzing. This is a simple example of a tiny bug in the test itself which fuzz testing catches quickly. A lot of the time, a crash happens because something is wrong in the fuzz harness itself, as opposed to a bug in the production code. This is why it can be useful to have targets or assertions that ensure that the fuzz test itself is correct.

Questions

1. Did you review the PR? Concept ACK, approach ACK, tested ACK, or NACK? What was your review approach?

2. What are the two new fuzz targets introduced and what are they testing? In terms of what they’re testing, how are they different from the other targets?

3. What are the benefits of separating out the fuzzing of the internal test helpers?

4. Were you able to run the clusterlin_linearize target? How many iterations (the first number libFuzzer shows at each line) did it take to produce a crash after making the s/chunking/simple_chunking/ change?

5. In commit 2763b75, why was --iterations_left moved?

6. In clusterlin_simple_finder, when finding a topologically valid subset to remove from the graph, why is it important to set non_empty to true? What could happen if we allowed empty sets?

7. In clusterlin_simple_linearize, why does the code only verify against all possible permutations when depgraph.TxCount() <= 8? What would happen if we tried to do this for larger transaction counts?

8. In commit 1e4f345, when a non-topological permutation is found, the code now fast forwards by reversing part of the permutation. Why does this optimization work, and how many permutations can it skip in the best case?

9. In SimpleCandidateFinder::FindCandidateSet(), the algorithm keeps track of two sets for each work unit: inc (transactions definitely included) and und (transactions that can still be added). Why does it need to track both sets instead of just tracking undecided transactions?

10. What is, no doubt, the coolest way to test code?

Meeting Log