Bitcoin Core getblockchaininfo RPC: Node-State Monitoring Guide

This guide explains Bitcoin Core getblockchaininfo RPC in plain English. It shows what the command does, what its result means and what it cannot prove.

Network identity

chain identifies main, test or regtest under the historical naming. Check it before interpreting any hash, height or balance and bind the expected genesis identity in higher-assurance systems. A responsive node on the wrong network is an operational failure, not a degraded success.

Blocks, headers and tip

blocks counts processed active-chain blocks while headers counts validated headers. A gap can be normal during initial sync or signal stalled block acquisition. Pair both with bestblockhash, median time and independent peer observations; equal heights alone do not prove equal chainwork or tip.

Progress and initial download

verificationprogress and initialblockdownload are estimates and debug-oriented signals. Use them with last-block age, chainwork and service-specific thresholds. Do not enable withdrawals because progress rounded to one or because IBD became false before monitoring and wallet rescans are complete.

Chainwork and difficulty

chainwork provides cumulative work in hexadecimal and difficulty describes the current target relative to the reference. Compare chainwork across compatible nodes to detect a lower-work branch. Preserve big integers exactly; converting long hexadecimal work to floating point can erase meaningful differences.

Pruning and disk

pruned changes the availability contract. Pruneheight gives the lowest complete stored block, while automatic settings and target size appear conditionally. Archive-dependent services must refuse assignment to a pruned node whose retained range cannot satisfy them. Monitor actual disk headroom beyond the configured target.

Soft forks and warnings

The response included legacy softfork and BIP 9 deployment state plus warnings. Status fields are version- and period-dependent; interpret defined, started, locked-in, active and failed under the named deployment. Warnings should page an operator under policy, not be discarded because historical safe mode was disabled.

Monitoring matrix

Test fresh, syncing, caught-up, pruned, stalled and forked regtest nodes. Validate conditional fields, schema changes, chainwork precision and warning handling. Gate each dependent service separately, because block explorers, mining templates, deposits and withdrawals have different readiness requirements.

Conclusion

getblockchaininfo is the core chain-health summary, but readiness emerges from a consistent set of identity, chainwork, freshness, pruning and warning signals. No single boolean or progress value is enough.