Learn how BIP 157 and BIP 158 help light clients find potentially relevant blocks, why matches can be false positives, and what validation still remains.
Ask a different question
A light wallet wants to find payments without downloading every full block. Sending a server an exact list of wallet addresses can reveal what the wallet is watching. Compact block filters move the first matching step to the client: it downloads small filter data and tests its own candidate scripts locally.
A filter is a compact representation of a defined set of block-related items. It is a search aid, not a miniature block, a list of wallet balances or a signature proving a payment belongs to you.
Encoding and transport are separate
BIP 158 specifies the compact filter construction, using a Golomb-coded set representation. BIP 157 specifies a peer-to-peer protocol for obtaining filters and related commitments, including filter headers and checkpoints. Understanding the distinction helps explain why a file format and a network request protocol are not the same feature.
The basic filter includes relevant script information for outputs and spent previous outputs under its defined rules. It does not simply index the human-readable address strings shown by an explorer. Unspendable OP_RETURN outputs are excluded from the basic output-script set.
A positive match is a candidate
A compact probabilistic representation can return false positives. A wallet may download a block because a filter matched and discover that none of its transactions concern the wallet. That is an expected cost of the encoding, not proof of a forged transaction.
A wallet tests locally
A wallet watches a group of scripts. It tests a downloaded filter without sending those scripts as a query. A positive result causes it to obtain the relevant block and inspect the actual outputs and previous-output relationships. Only that inspection determines whether its ledger should change; the filter match alone does not add a balance.
Be precise about negative results
A correctly constructed filter can answer its defined membership question without false negatives, but a client must still consider whether a peer supplied correct and complete filter data. Bitcoin block headers do not turn every arbitrary peer's filter into independently proven truth. Filter-header chains and comparison across peers are part of the protocol's design, not a substitute for understanding its trust assumptions.
A malicious or isolated peer set may withhold data. A full validating node and a light client also perform different levels of transaction and chain validation. Do not describe filter-based discovery as automatically equivalent to independently checking every consensus rule from genesis.
Privacy improves, but observation still matters
Local matching avoids directly disclosing the queried scripts in that first step. Later block requests, network addresses, peer selection and repeated access patterns can still leak information. The complete wallet design determines what an observer can infer.
Compact filters are useful when the goal is to identify blocks worth downloading. They are not a general full-history address API, do not recover missing signing keys, and do not certify the real-world identity of a transaction participant.
Sources and further reading
Key takeaways
- BIP 158 defines filter construction; BIP 157 defines retrieval and related protocol mechanisms.
- A match is a reason to inspect a block, not proof of a payment or balance.
- Local matching improves one privacy boundary but does not eliminate network observation or light-client trust assumptions.
Common questions
Can a filter match be wrong?
Yes. False positives are expected; inspect the actual block before recording wallet activity.
Does an OP_RETURN text search use the basic filter as a full text index?
No. Basic filters are not a general-purpose message archive, and their defined output set excludes OP_RETURN outputs.