Compact Block Filters

Anna is waiting for a payment in her phone wallet. A wallet is an application or device for receiving and sending bitcoin. Blocks are bundles of transactions, but the phone need not download every bundle in full. It can first scan small filters, rather like checking a book’s index before opening a relevant page. Every user receives the same summary for a given block and filter type; selecting what matters to Anna happens on her phone. The technical documents BIP 157 and BIP 158 divide the job: the former specifies how to obtain and check filters, the latter their content and construction. The wallet first verifies block headers, the basic records linking blocks into a chain, then obtains the filter checking data and the filters themselves. On a match, it downloads the full block and looks for the actual transaction. The similarly named Compact Blocks in BIP 152 solve a different problem: relaying new blocks quickly between nodes. A node is software that checks transactions and blocks and communicates with other participants in the network. [1] [2] [5] [6]

A Bitcoin transaction creates outputs: amounts with conditions for spending them later. The code expressing those conditions is called scriptPubKey. An input of a new transaction points to an earlier output being spent. The basic filter, identified by 0x00, therefore includes both new output scripts and the scripts of earlier outputs spent in the block. Anna can use it to look for money received or spent. New output scripts beginning with OP_RETURN, an instruction marking an unspendable output, are excluded. So is the special input of the coinbase transaction, which assigns the miner’s reward without spending an earlier output. Empty items are omitted and a repeated item is counted only once. This is not a list of all txid transaction identifiers, address strings or witness data such as signatures. Building the correct filter requires more than the new block itself: it also needs the earlier outputs spent by its transactions. [2]

A server could send Anna a summary that deliberately leaves out her payment. The wallet therefore checks not just a filter but its links to earlier filters. A hash is a short digital fingerprint of data. Applying SHA-256 twice to the stored filter produces its double-SHA256 hash. That fingerprint is joined to the preceding filter header and hashed the same way to make the next header. Changing an earlier filter consequently changes the checking data after it. However, the block header protected by mining does not contain a hash of this auxiliary filter chain. If every connected server supplies the same false chain, its fingerprints can still link up perfectly. Mathematical consistency alone does not establish that a summary matches the real block. [1]

BIP 157 therefore recommends connecting to several independent nodes, called peers in this exchange. A secure connection to a trusted node, such as your own, is an alternative. If the wallet receives conflicting filter chains, it finds the first disagreement. It can reconstruct the correct filter from that block and the necessary earlier outputs. The guarantee of identifying correct filters assumes at least one honest peer; several connections to the same attacker do not satisfy that condition. The chain itself can also change: during a reorganization, nodes replace part of its tip with a branch containing more accumulated proof of work. The wallet must follow that branch’s filters and reassess affected payments. A confirmation found earlier still depends on which chain the network accepts. [1] [2]

With the older BIP 37 approach, a wallet sent the server its own filter describing what it wanted to watch. Compact Block Filters reverse this: the wallet downloads general data and makes its personal selection locally. This reduces the information leaked about watched scripts. A provider still sees which full blocks Anna subsequently requests and may connect those requests to her IP address, the network address of her connection. Repeated visits may reveal further patterns. BIP 157 therefore recommends choosing full-block sources randomly from nodes to which the wallet has opened connections. A block can come from a different node than its filter. This improves privacy without guaranteeing anonymity. [1]

Filters describe blocks already included in the chain. They do not cover the current Mempool, the unconfirmed transactions a particular node holds for further relay or mining. A match does not prove that Anna owns the key needed to spend the money found, either. A private key is a secret numerical value that a wallet uses to create a digital signature authorizing a spend. The wallet must check the actual transaction and its inclusion in the block. A light client still does not verify every transaction in every block against all the rules as a Full Node does. That is a real security trade-off for using fewer resources. Availability is a separate issue: a Pruned Node can delete old blocks after verifying them while keeping their filters. Anna can then obtain the summary, but must get the full old block elsewhere. Pruning alone does not mean the node has stopped fully verifying the rules. [1] [5]

The small size comes with a trade-off: a filter can answer “possibly yes” even when the item is not in the block. This is a false positive. Anna then downloads a block unnecessarily, but her wallet will not find the supposed payment and must not count it. A correct filter does not miss an item that its rules actually include; that property does not excuse fabricated data from a dishonest server. Technically, SipHash-2-4 turns items into numbers in a range of size N × M, where N is the number of items. The numbers are sorted and their differences stored efficiently using Golomb-Rice coding. P=19 controls the coding; M=784931 affects random matches, with a probability of approximately 1/M for a single query outside the set. A byte is a standard unit of data size. The SipHash key is the first 16 bytes of the block hash in little-endian order, meaning less significant bytes come first. This is not a secret wallet key. Here, SipHash maps items to numbers for the filter; it does not encrypt them. The stored filter begins with N encoded in CompactSize, a format for nonnegative integers. [2]

At the 2026-10-17 review, both documents have Deployed status, indicating a deployed protocol, not support in every wallet. The following configuration example specifically concerns Bitcoin Core 29.0. The -blockfilterindex option builds a local filter index. Serving other nodes requires -peerblockfilters and a basic index; the NODE_COMPACT_FILTERS flag advertises support. The RPC programming interface provides getblockfilter, which returns the filter data and its header in fields named filter and header for a chosen block. Working RPC access alone therefore does not establish that other network nodes can obtain filters. For readers of the specification: getcfilters/cfilter carries filters, getcfheaders/cfheaders carries linking data, and getcfcheckpt/cfcheckpt supplies checkpoints in this auxiliary chain. These are network message names, not commands a mobile wallet user must type. [3] [4]