Bitcoin Core waitforblock RPC made simple. See what the feature does, where its limits sit and which checks node or wallet operators should make.
This guide explains Bitcoin Core waitforblock RPC in plain English. It shows what the command does, what its result means and what it cannot prove.
Bitcoin Core waitforblock RPC: The RPC waits for one exact block hash to become the active-chain tip. It does not merely wait for the block to be known, stored or buried under confirmations.
A miner is checking Bitcoin Core waitforblock RPC. Record the requested hash, start time and deadline. Compare the response. Classify success, timeout, shutdown and transport failure separately.
The RPC waits for one exact block hash to become the active-chain tip. It does not merely wait for the block to be known, stored or buried under confirmations.
timeout is expressed in milliseconds and defaults to zero, meaning no server-side timeout. Production callers should normally choose a bounded value that matches their recovery policy.
The result contains the current tip hash and height. On timeout or node exit those fields still return, so success requires returned hash equals requested hash.
A long server wait can outlast bitcoin-cli or application HTTP limits. Configure rpcclienttimeout deliberately, using zero only where an indefinite client connection is truly wanted.
A requested hash can become the tip and later leave the active chain. Downstream work requiring confirmations must separately track ancestry and depth rather than assuming the wait permanently settles state.
Use cancellation, jittered reconnects and a bounded number of waiters. A disconnected client should query the current tip before opening another blocking request.
Record the requested hash, start time and deadline; call waitforblock; compare the response; classify success, timeout, shutdown and transport failure separately; then verify any required confirmation depth. Build a revision-pinned evidence pack on an isolated node, wallet or protocol harness. Record source commit, binary hash, network, chain identity, configuration and dependencies.
Bitcoin Core waitforblock RPC: The RPC waits for one exact block hash to become the active-chain tip.
The RPC waits for one exact block hash to become the active-chain tip.
timeout is expressed in milliseconds and defaults to zero, meaning no server-side timeout.
The result contains the current tip hash and height. On timeout or node exit those fields still return, so success requires returned hash equals requested hash.
waitforblock is a precise notification primitive only when the caller validates its returned tip. Treat timeout responses, shutdown and reorganisations as normal states, not exceptional proof that the requested block was reached.
Check the current specification status and the documentation for the exact implementation you operate before moving production funds or changing a mining node.
Bitcoin Core waitfornewblock RPC made simple. See what the feature does, where its limits sit and which checks node or wallet operators should make.
Bitcoin Core waitforblockheight guide covering at-least height waits, timeout returns, response checks, reorganisations, client limits and reliable automation.
Bitcoin Core 26 submitpackage guide covering experimental child-with-parents packages, policy limits, fee results, replacements, propagation and safe submission.
Join the ASIC Mining Discussion
Members can read and join the discussion
Log in to read comments from other miners. Create a free account if you would like to ask a question or share your experience.
Membership helps us protect the discussion from spam and keep answers useful.