eth-bloom

library3.1.0pypypi✓ verified 86d ago

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.

serialization database

pip install eth-bloom

github ↗package ↗

INSTALL

IMPORT

SIG · ETH-BLOOM

eth-bloom

serializationpythonv3.1.0

Install

2.1s avg

Import

124ms

Disk

25MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.131s · 26.5MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.1s · import 0.116s · 28MB

25MB installed

● package 25MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BloomFilter

✓ from eth_bloom import BloomFilter

✗ from ethereum_bloom import BloomFilter

The PyPI package and import path were renamed from `ethereum-bloom` to `eth-bloom`.

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

Debug

Known issues

breakingThe 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 ...`.

affects: Prior to eth-bloom 0.4.0 (the renaming occurred before this version was established under the new name).

gotchaBloom 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.

affects: All versions (inherent to Bloom filter design).

gotchaEthereum'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.

affects: All versions (inherent to Ethereum's use of Bloom filters).

deprecatedThere 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.

affects: Future Ethereum protocol versions (post-EIP-7668, if accepted and implemented). The `eth-bloom` library itself would still function for local/custom bloom filters.

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'ethereum_bloom'

The `eth-bloom` library was previously named `ethereum-bloom`. Older code or tutorials might still refer to the old package name, which no longer exists as a separate installable package on PyPI.

fix

Install the correct package and update your import statements: `pip install eth-bloom` and change `from ethereum_bloom import BloomFilter` to `from eth_bloom import BloomFilter`.

TypeError: a bytes-like object is required, not 'str'

The `eth-bloom` library's `BloomFilter` methods, such as `add()` and membership checking (`in`), expect byte string inputs (e.g., `b'my_value'`), not regular Python strings.

fix

Ensure that all values passed to `BloomFilter` methods are encoded as byte strings. For example, use `b'your_string'` instead of `'your_string'`, or `value.encode('utf-8')` for dynamic strings. For hexadecimal strings like Ethereum addresses or topic hashes, use `bytes.fromhex(hex_string[2:])` after removing the '0x' prefix.

AttributeError: 'Eth' object has no attribute 'get_block'

This error occurs in the `web3.py` library, which is commonly used alongside `eth-bloom` to retrieve Ethereum block data. It indicates that you are using an outdated version of `web3.py` where method names like `getBlock` (camelCase) have been deprecated or changed to `get_block` (snake_case) in newer versions (typically v6.x and later).

fix

Upgrade your `web3.py` library to the latest version (`pip install web3 --upgrade`) and update your code to use the modern snake_case method names, such as `w3.eth.get_block()` instead of `w3.eth.getBlock()`.

Upgrade

Version history

3.1.0latest on PyPI · released Jan 8, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/ethereum/eth-bloom ↗

packagehttps://pypi.org/project/eth-bloom/ ↗