rpc, logging: add backgroundvalidation to getblockchaininfo

polespinasa commented at 11:02 pm on August 26, 2025: contributor

getblockchaininfo returns verificationprogress=1 and initialblockdownload=false even if there’s background validation. This PR adds information about background validation to rpc getblockchaininfo in a similar way to validationprogress does.

If assume utxo was used the output of a “sync” node performing background validation:

0$ ./build/bin/bitcoin-cli getblockchaininfo
1...
2  "mediantime": 1756245019,
3  "verificationprogress": 1,
4  "initialblockdownload": false,
5  "backgroundvalidation": true,
6  "backgroundvalidationprogress": 0.3114057065725397,
7  "chainwork": "0000000000000000000000000000000000000000dd66481a498addea9a2ac516",
8  "size_on_disk": 59449628660,
9...

If assume utxo was not used the progress is hidden and background validation is set to false:

0$ ./build/bin/bitcoin-cli getblockchaininfo
1...
2  "mediantime": 1756245700,
3  "verificationprogress": 1,
4  "initialblockdownload": false,
5  "backgroundvalidation": false,
6  "chainwork": "00000000000000000000000000000000000000000000000000000656d6bb052b",
7  "size_on_disk": 3964972194,
8...

DrahtBot commented at 11:02 pm on August 26, 2025: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33259.

Reviews

See the guideline for information on the review process.

Type	Reviewers
Concept ACK	yuvicc, luke-jr

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

yuvicc commented at 5:23 am on August 27, 2025: contributor

Concept ACK

luke-jr commented at 10:50 pm on August 27, 2025: member

Concept ACK. Would be nice to test the active state.

polespinasa commented at 11:12 pm on August 27, 2025: contributor

Would be nice to test the active state. @luke-jr what do you mean by active state?

bitcoin deleted a comment on Aug 27, 2025

luke-jr commented at 11:43 pm on August 27, 2025: member

When there is a background sync, not just false

luke-jr referenced this in commit 732ba0e131 on Aug 28, 2025

ajtowns commented at 0:56 am on August 28, 2025: contributor

Would it be better to return an object, eg:

0{
1    "background": {
2        "blocks": 100000,
3        "bestblockhash": "000000000003ba27aa200b1cecaad478d2b00432346c3f1f3986da1afd33e506",
4        "mediantime": 1293622620,
5        "chainwork": "0000000000000000000000000000000000000000000000000644cb7f5234089e"
6        "verificationprogress": 0.001,
7    }
8    ...
9}

polespinasa force-pushed on Aug 28, 2025

polespinasa commented at 2:32 am on August 28, 2025: contributor

@ajtowns sgtm, done. Not sure about the order thought… I’m open to suggestions.

in src/rpc/blockchain.cpp:1339 in 8efdfa9035 outdated

1335@@ -1336,6 +1336,15 @@ RPCHelpMan getblockchaininfo()
1336                 {RPCResult::Type::NUM_TIME, "mediantime", "The median block time expressed in " + UNIX_EPOCH_TIME},
1337                 {RPCResult::Type::NUM, "verificationprogress", "estimate of verification progress [0..1]"},
1338                 {RPCResult::Type::BOOL, "initialblockdownload", "(debug information) estimate of whether this node is in Initial Block Download mode"},
1339+                {RPCResult::Type::BOOL, "backgroundvalidation", "(debug information) estimate of whether this node is doing background validation"},

ajtowns commented at 5:04 am on August 28, 2025:

Can just drop this field, and use the presence/absence of the object to indicate where background validation is occurring?

If not, “estimate of” isn’t accurate here – the node knows whether it’s doing background validation or not.

polespinasa commented at 6:30 pm on August 28, 2025:

I like to see false if it’s not in b validation. Fixed the “estimate of”

in src/rpc/blockchain.cpp:1344 in 8efdfa9035 outdated

1335@@ -1336,6 +1336,15 @@ RPCHelpMan getblockchaininfo()
1336                 {RPCResult::Type::NUM_TIME, "mediantime", "The median block time expressed in " + UNIX_EPOCH_TIME},
1337                 {RPCResult::Type::NUM, "verificationprogress", "estimate of verification progress [0..1]"},
1338                 {RPCResult::Type::BOOL, "initialblockdownload", "(debug information) estimate of whether this node is in Initial Block Download mode"},
1339+                {RPCResult::Type::BOOL, "backgroundvalidation", "(debug information) estimate of whether this node is doing background validation"},
1340+                {RPCResult::Type::OBJ, "background", /*optional=*/true, "state info regarding background validation process",
1341+                {
1342+                    {RPCResult::Type::NUM, "blocks", /*optional=*/true, "the height of the most-work fully-background validated chain. The genesis block has height 0"},
1343+                    {RPCResult::Type::STR, "bestblockhash", /*optional=*/true, "the hash of the currently best block validated in background"},
1344+                    {RPCResult::Type::NUM_TIME, "mediantime", /*optional=*/true, "The median block time expressed in " + UNIX_EPOCH_TIME},

ajtowns commented at 5:11 am on August 28, 2025:

Could make it the instead of The for consistency with other options. Could consider doing the same for the main mediantime help text that this was copied from too.

As far as ordering goes, probably copy the ordering of the fields in getblockchaininfo?

polespinasa commented at 6:29 pm on August 28, 2025:

done

in src/rpc/blockchain.cpp:1397 in 8efdfa9035 outdated

1392+        const CBlockIndex& btip{*CHECK_NONFATAL(chainman.GetBackgroundSyncTip())};
1393+        bValidation.pushKV("blocks",btip.nHeight);
1394+        bValidation.pushKV("bestblockhash", btip.GetBlockHash().GetHex());
1395+        bValidation.pushKV("mediantime", btip.GetMedianTimePast());
1396+        bValidation.pushKV("chainwork", btip.nChainWork.GetHex());
1397+        bValidation.pushKV("verificationprogress", chainman.GuessVerificationProgress(&btip));

ajtowns commented at 5:24 am on August 28, 2025:

This is telling you how far the background has progressed if it were going to go all the way to the current tip; but it will actually stop when it hits the snapshot block. So I think this should be calling a new method chainman.GetBackgroundVerificationProgress(btip), something like:

0double ChainstateManager::GetBackgroundVerificationProgress(const CBlockIndex* tip)
1{
2    if (tip == nullptr) return 0.0;
3    auto base = GetSnapshotBaseBlock();
4    if (base == nullptr || base->m_chain_tx_count == 0) return 0.0;
5    return tip->m_chain_tx_count / base->m_chain_tc_count;
6}

polespinasa commented at 6:48 pm on August 28, 2025:

That’s a good point, but that’s actually what we are showing in the logs. Do we want to keep consistency between both? Update maybe also the logging?

[background validation] UpdateTip: new best=00000000000000000007b796179f5abb7eed59f736e3418eb8381c29eb78527a height=744000 version=0x20400004 log2_work=93.616004 tx=747106639 date='2022-07-07T14:47:25Z' progress=0.605933 cache=358.0MiB(2606151txo)

In validation.cpp

0constexpr int BACKGROUND_LOG_INTERVAL = 2000;
1        if (pindexNew->nHeight % BACKGROUND_LOG_INTERVAL == 0) {
2            UpdateTipLog(m_chainman, coins_tip, pindexNew, __func__, "[background validation] ", "");
3        }

0static void UpdateTipLog( ... const CBlockIndex* tip,...)
1{
2
3   ...
4                   FormatISO8601DateTime(tip->GetBlockTime()),
5                   chainman.GuessVerificationProgress(tip),
6   ...
7}

in test/functional/rpc_blockchain.py:176 in 8efdfa9035 outdated

170@@ -170,6 +171,10 @@ def _test_getblockchaininfo(self):
171         assert res['pruned']
172         assert not res['automatic_pruning']
173 
174+        # check background validation
175+        assert not res['backgroundvalidation']
176+        assert "background" not in res.keys()

ajtowns commented at 5:29 am on August 28, 2025:

Should be able to test the field-exists case via feature_assumeutxo.py probably just prior to the invocation of n1.submitblock(snapshot_block)

polespinasa commented at 9:19 pm on August 28, 2025:

do we want to test that in feature_assumeutxo.py or in rpc_blockchain.py

polespinasa force-pushed on Aug 28, 2025

polespinasa commented at 9:00 pm on August 28, 2025: contributor

2d48902999a7ad1fcf19a8e630c69d6228dbd373 added snapshot height

83a1721817fda4db88ba12e0395ed63ba064c41b modify the way verification progress is calculated for background validation -> context: #33259 (review)

polespinasa force-pushed on Aug 28, 2025

in src/rpc/blockchain.cpp:1342 in 2d48902999 outdated

1340                 {RPCResult::Type::NUM, "verificationprogress", "estimate of verification progress [0..1]"},
1341                 {RPCResult::Type::BOOL, "initialblockdownload", "(debug information) estimate of whether this node is in Initial Block Download mode"},
1342+                {RPCResult::Type::BOOL, "backgroundvalidation", "(debug information) whether this node is doing background validation"},
1343+                {RPCResult::Type::OBJ, "background", /*optional=*/true, "state info regarding background validation process",
1344+                {
1345+                    {RPCResult::Type::NUM, "snapshotheight", /*optional=*/true, "the heigh of the snapshot block"},

maflcko commented at 10:56 am on August 29, 2025:

"the heigh of the snapshot block" -> "the height of the snapshot block" [spelling error: "heigh" should be "height"]

in src/validation.h:1167 in 2d48902999 outdated

1162@@ -1163,6 +1163,9 @@ class ChainstateManager
1163     /** Guess verification progress (as a fraction between 0.0=genesis and 1.0=current tip). */
1164     double GuessVerificationProgress(const CBlockIndex* pindex) const EXCLUSIVE_LOCKS_REQUIRED(GetMutex());
1165 
1166+    /** Guess background verification progress in case assume utxo was used (as a fraction between 0.0=genesis and 1.0=snapshot blocks). */
1167+    double GetBackgroundVerificationProgress(const CBlockIndex* pindex) const EXCLUSIVE_LOCKS_REQUIRED(GetMutex());

maflcko commented at 10:59 am on August 29, 2025:

0    /** Guess background verification progress in case assume-utxo was used (as a fraction between 0.0=genesis and 1.0=snapshot blocks). */
1    double GetBackgroundVerificationProgress(const CBlockIndex& block) const EXCLUSIVE_LOCKS_REQUIRED(GetMutex());

can remove the unused nullptr handling here, as all call-sites already dereferenced the pointer

polespinasa commented at 7:49 pm on August 29, 2025:

Done

log: update progress calculations for background validation

updates estimations to the block snapshot instead of the main chain tip as it will stop validation after reaching that height

471092ca98

rpc, log: add backgroundvalidation to getblockchaininfo 01860ea0e5

polespinasa force-pushed on Aug 29, 2025

rpc, logging: add backgroundvalidation to getblockchaininfo #33259

Code Coverage & Benchmarks

Reviews