Solo Mining Calculator: Estimate Odds and Timeframes
Use a solo mining calculator correctly: enter productive hashrate, network conditions, uptime and time horizon, then read expected time and probability without.
Read article
ASIC mining knowledge centre
Bitcoin Core waitforblock RPC: Exact Block Automation Guide
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.
TL;DR
- What it is: Bitcoin Core 30.0 exposes waitforblock as a public blockchain RPC. It blocks until the nominated block hash becomes the chain tip or the optional timeout expires.
- Why it matters: 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.
- Current position: Require a second reviewer and explicit rollback or expiry, and pause payments, signing or network-dependent services until post-change evidence is complete.
What this means in simple English
An RPC is a command sent to one Bitcoin Core node. It can ask that node for information or request a local action. A successful reply describes that node; it does not automatically prove what happened across the Bitcoin network.
Beginners can focus on the input, the result and the limit of that result. Operators should test the command on the exact Bitcoin Core version they run before relying on it.
Simple example
Think of a mempool as one node’s waiting room for valid transactions that have not yet entered a block. Different nodes can have different waiting rooms, and the contents can change from one second to the next.
Key terms in plain English
- Bitcoin Core:
- Widely used software that validates Bitcoin and can provide wallet, network and operator tools.
- RPC:
- A command that software sends to a node to request information or a local action.
- Node:
- A computer running Bitcoin software that checks data and communicates with other peers.
Exact condition
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
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.
Response validation
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.
Client settings
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.
Reorganisations
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.
Concurrency
Use cancellation, jittered reconnects and a bounded number of waiters. A disconnected client should query the current tip before opening another blocking request.
Operational pattern
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.
Frequently asked questions
What is Bitcoin Core waitforblock RPC?
Bitcoin Core 30.0 exposes waitforblock as a public blockchain RPC. It blocks until the nominated block hash becomes the chain tip or the optional timeout expires.
Is Bitcoin Core waitforblock RPC active or supported today?
Require a second reviewer and explicit rollback or expiry, and pause payments, signing or network-dependent services until post-change evidence is complete.
Why does Bitcoin Core matter?
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.
Do beginners need to use the technical details?
No. The command is mainly for people who operate Bitcoin Core or software connected to it. Other readers can use the article to understand what an operator or service is measuring.
Conclusion
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.
Primary sources
Check the current specification status and the documentation for the exact implementation you operate before moving production funds or changing a mining node.
On this page
Search More Guides
BIP-110 Explained: Rules, Signalling and Why It Closed
BIP-110 Explained made simple. See the main facts, costs, risks and practical checks before you make a decision.
Read article
Bitcoin Core 29.4 Release: Chainstate Disk I/O Guide
Bitcoin Core 29.4 guide covering repeated chainstate rewrites, regular compaction, LevelDB seek compaction, transaction-data lifetime and wallet sizing fixes.
Read article
Need Advice for Your Mining Setup?
Use our guidance to build your shortlist, then speak to our team when you want help comparing hardware, power, hosting or repairs.