Client-side block filtering

From Bitcoin Wiki
Jump to navigation Jump to search

Client-side block filtering (also called client side bloom filters or committed bloom filters) is a way for lightweight wallets to synchronize their history and balance. It is aimed to preserve the privacy of the users and to resist lies-by-omission from third-party servers or nodes.

The protocol works by having filters created that contains all the addresses for every transaction in a block. The filters can test whether an element is in the set; false positives are possible but not false negatives. A lightweight wallet would download all the filters for every block in the blockchain and check for matches with its own addresses. Blocks which contain matches would be downloaded in full from the peer-to-peer network, and those blocks would be used to obtain the wallet's history and current balance.


The scheme is similar to BIP37 but with much better privacy.

The privacy properties come from a few features:

  • The wallet addresses are never sent to any other entity, even indirectly.
  • Implementing wallets would download full blocks just like any other node on the bitcoin p2p network, so peers may not realize the downloaded blocks are important. Blocks are the natural unit of pagination for the block chain.
  • Implementing wallets can download full blocks in parallel from several different nodes (but an internet service provider could still see all the downloaded blocks).
  • Each block typically has a few thousand addresses in it, so there is a large anonymity set for which individual address caused a filter match.
  • Filters have a false positive rate so not every downloaded block indicates a filter match.

Privacy-relevant information is still leaked if the adversary can figure out which blocks have been downloaded by the wallet.

It may be possible for an adversary to find the wallet addresses of a given wallet by using data fusion of which blocks are downloaded and the transaction graph in the public block chain.

Data fusion between the transaction graph information on the blockchain and the list of downloaded blocks can reveal the wallet addresses in certain situations. A model and calculations regarding this have been published on the Bitcoin developer mailing list[1] which show how client-side block filtering works best for privacy when the wallet makes only a few of its own transactions. This can be made harder by stopping the adversary finding which blocks have been downloaded, perhaps by downloading each set of blocks with a new Tor circuit.

Although privacy from client-side block filtering is believed to be very good, the best privacy for wallet synchronization is obtained by using a full node which downloads all blocks.

Consensus-critical filters

It is proposed that a future softfork would be done which adds a new consensus rule that requires miners to include the filters in each block. Then the economic majority would enforce the correctness of those filters, and so lightweight wallets would have a very trustworthy source of filters. As of 2019 such a softfork has not been activated so implementations of client-side block filtering obtain their filters from semi-trusted servers. Which ever implementation ends up being soft-forked would have to be included in bitcoin code forever (unless the soft fork rule has a sunset provision), so the bitcoin community must take care in deciding if and how to add such a rule.


One implementation of client-side block filtering is Neutrino also known as BIP157 and BIP158 which is used by some Lightning Network lightweight wallets.

External links