ethereum-bloom-filters is a JavaScript/TypeScript library designed to efficiently test Ethereum bloom filters for set membership, currently at version 1.2.0. It provides a lightweight client for probabilistic checks, allowing developers to quickly ascertain if a particular address, topic, or other data might be present within a block's logBlooms without requiring a full node query. The package has a minimal dependency footprint, relying solely on `@noble/hashes` for its cryptographic hashing primitives, which is notably funded by the Ethereum Foundation. This approach helps reduce the computational overhead associated with monitoring on-chain events, such as updating user balances, by minimizing unnecessary database queries. While no explicit release cadence is documented, its active maintenance is implied by npm activity and recent versioning. A key differentiator is its focus on standalone bloom filter testing, offering a direct utility for common Ethereum development patterns.
npm install ethereum-bloom-filtersVerified import paths — ran on the pinned version, not inferred.
Demonstrates how to import and use the core bloom filter testing functions (`isUserEthereumAddressInBloom`, `isTopicInBloom`, `isInBloom`) to check for the probabilistic presence of addresses, topics, or generic values within a given Ethereum bloom filter string.
Always understand that 'true' results require further verification (e.g., querying the actual logs or contract state) if absolute certainty is needed. 'False' results are definitive.
For browser-only usage without a bundler, download the appropriate script from the `web-scripts` directory (e.g., `web-scripts/ethereum-bloom-filters.min.js`) and include it in your HTML. The library will then be available globally as `ethereumBloomFilters`.
When using bloom filters, remember they are only useful for checking the probabilistic presence of event data (logs) generated by contracts. For ETH transfers or contract interactions that do not emit events, other methods (e.g., checking account balances or transaction data directly) are required.
Developers should be aware of the long-term deprecation of bloom filters within the Ethereum protocol. For future-proof applications, consider alternative event indexing solutions (e.g., centralized indexers, ZK-SNARKs for provable log indexes) or rely on full node RPC calls for historical data, as `eth_getLogs` would still be supported for full nodes. This library's utility will diminish for newly generated blocks post-EIP-7668 implementation.
Use ES Module `import` syntax: `import { isBloom, ... } from 'ethereum-bloom-filters';`. If targeting a browser without a bundler, include the pre-built script tag as per the documentation.If using CommonJS, ensure you're calling `require('ethereum-bloom-filters')` and then accessing named exports directly on the returned object (e.g., `ethereumBloomFilters.isBloom`). If using ES Modules, ensure named imports are used: `import { isBloom } from 'ethereum-bloom-filters';`.The library supports both ESM and CJS. Ensure your project's `tsconfig.json` (for TypeScript) or build configuration (Webpack, Rollup, Parcel) correctly resolves ES Modules. For pure Node.js ESM environments, named imports should work directly. If persistent, verify the package's `package.json` `exports` field or try CJS `require` if in a compatible environment.