Bitcoin Core getblockfilter RPC: Compact Filter Guide

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

Index prerequisite

Start the node with blockfilterindex enabled and allow historical construction to complete. The 0.19 release notes estimated roughly 4 GiB and stated that this release exposed filters locally rather than serving them over P2P.

Block identity

Require a canonical 32-byte block hash on the expected chain. Record height and active-chain status because an otherwise valid filter for a stale branch can produce a misleading scan result.

Filter type

The documented default is basic. Reject unknown names explicitly and bind parsing to the historical BIP 158 parameters instead of guessing from returned bytes.

Filter bytes

The filter is a probabilistic compressed representation of selected block scripts. A match is a reason to fetch and inspect the full block, not proof that a payment exists or belongs to the wallet.

Filter header

The header commits to the current filter and previous filter header, enabling chain consistency checks. Verify it against independently get checkpoints or peers rather than trusting the same source twice.

Privacy boundary

Client-side matching avoids revealing addresses to a remote query service, but wallet scripts and match results remain sensitive. Keep scanning local and minimise logs.

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

getblockfilter is a precise local primitive for compact-filter clients. It is safe only when index readiness, block identity, BIP 158 decoding and independent filter-header verification are all explicit.