Bitcoin Core listsinceblock RPC: Reorg-Aware Wallet Feed

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

Checkpoint input

Persist the exact lastblock hash from a completed run and feed it into the next call. A height is insufficient because reorganisations can replace a block at the same height. Omission requests all wallet history and can be expensive.

Target-confirmations trap

target_confirmations defaults one and selects the main-chain block returned as lastblock. It does not filter the transaction array. A value such as six intentionally re-notifies transactions until the cursor trails the tip by the chosen depth.

Removed array

include_removed defaults true and returns wallet effects removed by reorganisation, although pruned nodes may not guarantee it. Apply removals idempotently before finalising the next cursor and preserve evidence if a transaction is later re-added.

Fork-point behaviour

When the input hash is no longer active, transactions from the fork point onward are included so a consumer can reconcile competing history. Validate active ancestry and do not discard duplicate-looking events without comparing state.

Transaction fields

Send amounts and fees are negative, receive positive, confirmations below zero indicate conflict depth, and BIP125 state can be unknown. Deprecated account, comments and labels are metadata. Reconcile every monetary field in satoshis.

Watch-only and pruning

include_watchonly changes wallet scope; include_removed on pruned nodes has limitations. Record both, assign archive-capable roles where reorg completeness matters and cross-check independent chain and wallet evidence.

How specialists test it

Operators test the command on a non-production node first. They check a normal reply, an invalid request, a timeout and a restart. This shows what the response means and prevents one local result from being mistaken for a network-wide outcome.

Conclusion

listsinceblock supports a robust wallet event feed only when its cursor, re-notification and removed-event semantics are honoured. It is designed for reorg reconciliation, not simple one-pass pagination.