{"id":6620,"library":"eth-bloom","title":"eth-bloom","description":"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.","status":"active","version":"3.1.0","language":"en","source_language":"en","source_url":"https://github.com/ethereum/eth-bloom","tags":["ethereum","bloom filter","blockchain","evm","cryptography"],"install":[{"cmd":"pip install eth-bloom","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The PyPI package and import path were renamed from `ethereum-bloom` to `eth-bloom`.","wrong":"from ethereum_bloom import BloomFilter","symbol":"BloomFilter","correct":"from eth_bloom import BloomFilter"}],"quickstart":{"code":"from eth_bloom import BloomFilter\n\n# Create an empty BloomFilter\nb1 = BloomFilter()\nb2 = BloomFilter()\n\n# Add items (must be bytes)\nb1.add(b'a')\nb1.add(b'common')\nb2.add(b'b')\nb2.add(b'common')\n\n# Check for membership\nprint(b'a' in b1)       # True\nprint(b'b' in b1)       # False\nprint(b'common' in b1)  # True\n\n# Bloom filters can be combined (union operation)\nb3 = b1 + b2\nprint(b'a' in b3)       # True\nprint(b'b' in b3)       # True\nprint(b'common' in b3)  # True\n\n# Initialize from an integer representation (e.g., a block's logsBloom)\nbloom_int_representation = int(b1)\nb_from_int = BloomFilter(bloom_int_representation)\nprint(b'a' in b_from_int) # True","lang":"python","description":"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."},"warnings":[{"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 ...`.","message":"The package name and import path were changed from `ethereum-bloom` to `eth-bloom`. Older projects might still reference the deprecated name.","severity":"breaking","affected_versions":"Prior to eth-bloom 0.4.0 (the renaming occurred before this version was established under the new name)."},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions (inherent to Bloom filter design)."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (inherent to Ethereum's use of Bloom filters)."},{"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.","message":"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.","severity":"deprecated","affected_versions":"Future Ethereum protocol versions (post-EIP-7668, if accepted and implemented). The `eth-bloom` library itself would still function for local/custom bloom filters."}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}