Bitcoin Core waitfornewblock 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 waitfornewblock RPC in plain English. It shows what the command does, what its result means and what it cannot prove.
Bitcoin Core waitfornewblock RPC: A new tip, timeout and node exit all return a hash and height. A response is not proof of change.
A miner is checking Bitcoin Core waitfornewblock RPC. Persist the last fully processed tip, wait from that state, compare, fetch the path difference, apply idempotently and commit the new checkpoint only after downstream work succeeds.
Supply the last processed hash and height as current_tip where supported. This closes the race between reading the tip and beginning the blocking call.
A new tip, timeout and node exit all return a hash and height. A response is not proof of change; compare it with the supplied baseline.
A higher height usually represents extension but is not enough proof. Query headers or chain ancestry to identify replacements, same-height changes and deeper reorganisations.
The millisecond timeout defaults to zero. Choose bounded waits for health checks and cancellation, while ensuring client and reverse-proxy limits exceed the chosen server wait.
Persist the last fully processed tip, wait from that state, compare, fetch the path difference, apply idempotently and commit the new checkpoint only after downstream work succeeds.
On transport failure or restart, query the active tip and reconcile from the durable checkpoint. Never assume a missed connection means no blocks arrived.
One coordinated watcher can distribute internal events more safely than many unbounded RPC waiters. Add back-pressure, deduplication and observability for lag and reorg depth. Build a revision-pinned evidence pack on an isolated node, wallet or protocol harness.
Bitcoin Core waitfornewblock RPC: A new tip, timeout and node exit all return a hash and height.
Supply the last processed hash and height as current_tip where supported. This closes the race between reading the tip and beginning the blocking call.
A new tip, timeout and node exit all return a hash and height.
A higher height usually represents extension but is not enough proof. Query headers or chain ancestry to identify replacements, same-height changes and deeper reorganisations.
waitfornewblock is a low-overhead tip-change primitive, not a complete event system. Durability comes from checkpointing, explicit comparison, ancestry reconciliation and idempotent downstream processing.
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 waitforblockheight guide covering at-least height waits, timeout returns, response checks, reorganisations, client limits and reliable automation.
Bitcoin Core waitforblock RPC made simple. See what the feature does, where its limits sit and which checks node or wallet operators should make.
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.