Block Filter Index

The block filter index is an optional Bitcoin Core database, enabled with -blockfilterindex=basic, that precomputes a compact filter for every block on the chain. These filters follow BIP158, which encodes the scripts and outpoints touched by a block into a probabilistic Golomb-Rice Coded Set (GCS). A light client downloads only the small filter, tests it against its own addresses, and fetches a full block only when the filter signals a possible match. Stored under indexes/blockfilter/basic/, the index is what lets a full node serve BIP157 light clients without ever learning which addresses those clients care about.

Why filters beat bloom filters

The older BIP37 bloom-filter approach let a light wallet ask a server to filter blocks for it, which leaked the wallet's addresses to whichever node it connected to — a privacy hole large enough that chain-surveillance operations exploited it in the wild. BIP158 inverts the trust model: the full node builds one deterministic filter per block and serves the identical filter to everyone. The wallet does the matching locally, so a spy node never learns the wallet's scripts. It cannot even distinguish a wallet syncing its own history from a node idly fetching filters. A GCS matches every real member with certainty and non-members only with a small false-positive rate, so a wallet may occasionally download an irrelevant block — which itself adds a little plausible cover — but never misses one of its own transactions.

How the pieces fit

The division of labour is defined across two BIPs: BIP158 specifies the filter construction itself — covered in more depth under compact block filters (BIP158) — while BIP157 defines the peer-to-peer messages for requesting filters, filter headers, and checkpoints. Filter headers chain each filter to its predecessor, letting a client cheaply detect a node serving doctored filters by cross-checking headers from multiple peers. Serving filters to the network requires enabling -peerblockfilters alongside the index; the index alone also powers fast local wallet rescans, since Bitcoin Core can test filters instead of reading every raw block off disk.

Cost and use cases

Building the index adds a few gigabytes of disk and some one-time processing after initial block download, after which it maintains itself with each new block. In return it becomes the backbone of privacy-preserving light wallets, Neutrino-style clients, and self-hosted wallet backends you run against your own node rather than a third party's server. Sovereign Bitcoiners who serve their phone wallet from a home node typically enable this index for exactly that reason: it gives the phone SPV-grade lightness with none of the address leakage of connecting to someone else's infrastructure.

Running it well

The design also embodies a principle worth naming: push work to the edge, keep trust at the edge. Every alternative — Electrum servers, wallet-vendor APIs, block explorers — answers the same question faster by having someone else's machine do the matching, and every one of them learns your addresses in the process. BIP157/158 accepts a little client-side bandwidth and computation as the price of telling nobody anything, which is the same trade a sovereign Bitcoiner makes every time they choose their own node over someone else's convenience.

On a home node the practical costs are modest and the toggle is one line in bitcoin.conf. The index builds in the background, and the node stays fully usable meanwhile. If you juggle memory limits on constrained hardware, index building is one of the workloads that benefits from a generous dbcache during sync. For the other optional lookup structures a node can maintain, see the transaction index (txindex) — a different tool for a different question, resolving arbitrary historical transactions rather than watching for wallet-relevant blocks.