eth-bloom

3.1.0 · active · verified Wed Apr 15

eth-bloom is a Python library providing an implementation of the bloom filter used by Ethereum. It allows for efficient probabilistic checks of set membership, commonly used to quickly detect the likely presence of event logs within Ethereum blocks and transaction receipts. The library is actively maintained by the Ethereum Foundation and regularly updated to support modern Python versions.

Warnings

breaking The package name and import path were changed from `ethereum-bloom` to `eth-bloom`. Older projects might still reference the deprecated name.
Fix: Update your `pip install` command to `pip install eth-bloom` and change all import statements from `from ethereum_bloom import ...` to `from eth_bloom import ...`.
gotcha Bloom filters are probabilistic data structures that can produce 'false positives'. This means the filter might indicate an item *could* be present when it is not, but it will never report an item as absent if it is actually present ('false negatives' are guaranteed not to occur).
Fix: Always perform a definitive check on the underlying data (e.g., actual transaction logs or database) if a Bloom filter indicates a potential match. The filter is best used for quickly ruling out non-matches.
gotcha Ethereum's Bloom filters are specifically designed for detecting event *logs* (emitted by smart contracts) within blocks or transaction receipts. They are not effective for filtering general transaction data, such as pure ETH transfers, which do not emit logs.
Fix: Understand that `eth-bloom` is primarily useful for filtering contract events (e.g., ERC20 `Transfer` events) and should not be relied upon for other types of on-chain activity.
deprecated There is an active Ethereum Improvement Proposal (EIP-7668) to remove Bloom filters from block headers in the Ethereum protocol by requiring them to be empty. If implemented, this would deprecate the primary use case of `eth-bloom` for inspecting on-chain block data.
Fix: Monitor Ethereum protocol developments for the status and implementation of EIP-7668. Be prepared to adapt usage patterns if block header Bloom filters are removed or emptied in a future hard fork.

Install

pip install eth-bloom Install latest version

Imports

BloomFilter
wrong:
```
from ethereum_bloom import BloomFilter
```
correct:
```
from eth_bloom import BloomFilter
```
The PyPI package and import path were renamed from `ethereum-bloom` to `eth-bloom`.

Quickstart

Demonstrates how to create, populate, query, and combine Ethereum-style Bloom filters, as well as initialize one from an integer representation. Items added to the filter must be byte strings.

from eth_bloom import BloomFilter

# Create an empty BloomFilter
b1 = BloomFilter()
b2 = BloomFilter()

# Add items (must be bytes)
b1.add(b'a')
b1.add(b'common')
b2.add(b'b')
b2.add(b'common')

# Check for membership
print(b'a' in b1)       # True
print(b'b' in b1)       # False
print(b'common' in b1)  # True

# Bloom filters can be combined (union operation)
b3 = b1 + b2
print(b'a' in b3)       # True
print(b'b' in b3)       # True
print(b'common' in b3)  # True

# Initialize from an integer representation (e.g., a block's logsBloom)
bloom_int_representation = int(b1)
b_from_int = BloomFilter(bloom_int_representation)
print(b'a' in b_from_int) # True

view raw JSON →