Home › Glossary › Compact block filters

Compact block filters

Also called: Neutrino, BIP 157, BIP 158, client-side block filtering, GCS filters, cfilters.

Compact block filters (BIP 157 and 158) are small per-block summaries that let light wallets find their transactions without revealing their addresses.

Compact block filters let a light wallet find which blocks contain its transactions without telling anyone which addresses it cares about. A full node builds one small filter per block; the wallet downloads the filters, tests them locally against its own scripts, and fetches only the blocks that match. The filter format is in BIP 158, by Olaoluwa Osuntokun and Alex Akselrod, and the peer-to-peer protocol in BIP 157, by the same authors with Jim Posen. The best-known client is Neutrino.

How compact block filters work

  • What goes in. The "basic" filter holds, for every transaction in the block, the scriptPubKey of each output (except OP_RETURN outputs) and the script of each output being spent.
  • How it's compressed. Items are hashed with SipHash and stored as a Golomb-coded set with P = 19 and M = 784931, so an unrelated item matches with a probability of about 1 in 784,931.
  • How it's checked. Each filter's hash is chained into a 32-byte filter header, much like block headers. A client that asks several peers for filter headers can spot a peer serving a bad filter, as long as one peer is honest.
  • Messages: getcfilters and cfilter, getcfheaders and cfheaders, getcfcheckpt and cfcheckpt.

Compact filters vs Bloom filters

With BIP 37 Bloom filters, the wallet sends its filter to the node, which reveals much of the wallet and makes the node do work for each client. With compact filters the node serves the same filter to everyone and learns only which blocks the wallet downloads. The cost is more bandwidth.

Bitcoin Core can build and serve these filters (options blockfilterindex and peerblockfilters). They are now the main privacy-preserving alternative to classic SPV for mobile and Lightning wallets.

BIPs that define Compact block filters

  • BIP 157: Client Side Block Filtering: Deployed. Defines a protocol for lightweight wallets in which full nodes publish compact summaries (filters) of each block, and wallets download them to check locally which blocks matter. Unlike the older…
  • BIP 158: Compact Block Filters for Light Clients: Deployed. Specifies how to build the compact block filters used by the BIP 157 light-client protocol, a compressed summary of the addresses and data touched in each block. Wallets use these filters to decide…
  • BIP 37: Connection Bloom filtering: Deployed. Lets lightweight wallets hand a full node a Bloom filter (a compact, approximate summary of what they care about) so they receive only relevant transactions. This made phone wallets practical,…

Related terms

  • Bloom filter: A Bloom filter is a compact probabilistic set; BIP 37 used one so light wallets could ask full nodes for only the transactions matching their addresses.
  • SPV (Simplified Payment Verification): SPV (Simplified Payment Verification) is how light wallets check payments using only block headers and Merkle proofs, without downloading full blocks.
  • Node: A Bitcoin node is a computer running Bitcoin software that downloads, checks and relays blocks and transactions; a full node verifies every rule itself.
  • Merkle tree: A Merkle tree hashes many items into one 32-byte root, so any single item can be proven to be included with a short proof instead of the whole list.