{"id":15323,"library":"ethereum-bloom-filters","title":"Ethereum Bloom Filters Client","description":"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.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/joshstevens19/ethereum-bloom-filters","tags":["javascript","ethereum","blockchain","blooms","bloom","bloom filters","typescript"],"install":[{"cmd":"npm install ethereum-bloom-filters","lang":"bash","label":"npm"},{"cmd":"yarn add ethereum-bloom-filters","lang":"bash","label":"yarn"},{"cmd":"pnpm add ethereum-bloom-filters","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides cryptographic hashing functions essential for bloom filter operations. It is a core runtime dependency.","package":"@noble/hashes","optional":false}],"imports":[{"note":"Primary usage is with named ESM imports for individual functions. Direct CommonJS `require()` returns an object with all exports.","wrong":"const isBloom = require('ethereum-bloom-filters').isBloom;","symbol":"isBloom","correct":"import { isBloom } from 'ethereum-bloom-filters';"},{"note":"CommonJS `require()` syntax assigns all exports to a single object. There is no default export, so `import ethereumBloomFilters from '...'` will fail. For browser environments without a bundler, a global `ethereumBloomFilters` object is exposed after script inclusion.","wrong":"import ethereumBloomFilters from 'ethereum-bloom-filters';","symbol":"ethereumBloomFilters","correct":"const ethereumBloomFilters = require('ethereum-bloom-filters');"},{"note":"Always ensure the library is loaded and assigned to a variable, or use named ESM imports when accessing these utility functions.","wrong":"ethereumBloomFilters.isUserEthereumAddressInBloom(); // without prior require() or script tag","symbol":"isUserEthereumAddressInBloom","correct":"import { isUserEthereumAddressInBloom } from 'ethereum-bloom-filters';"}],"quickstart":{"code":"import { isUserEthereumAddressInBloom, isTopicInBloom, isInBloom } from 'ethereum-bloom-filters';\n\n// Example Ethereum block bloom (a 256-byte hex string, actual bloom from a real block would be much longer)\nconst blockBloom = '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000';\n// A fake Ethereum address (20 bytes)\nconst userAddress = '0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B'; \n// A fake topic (32 bytes)\nconst eventTopic = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';\n\nconst isAddressLikelyPresent = isUserEthereumAddressInBloom(blockBloom, userAddress);\nconst isTopicLikelyPresent = isTopicInBloom(blockBloom, eventTopic);\nconst isGenericValueLikelyPresent = isInBloom(blockBloom, 'some_arbitrary_value');\n\nconsole.log(`Is address ${userAddress} likely in bloom? ${isAddressLikelyPresent}`); // Should be false with an empty bloom\nconsole.log(`Is topic ${eventTopic} likely in bloom? ${isTopicLikelyPresent}`);   // Should be false with an empty bloom\nconsole.log(`Is generic value likely in bloom? ${isGenericValueLikelyPresent}`); // Should be false with an empty bloom\n\n// Note: Bloom filters are probabilistic. A 'true' result means it *might* be present (false positive possible).\n// A 'false' result means it is *definitely not* present (no false negatives).","lang":"typescript","description":"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."},"warnings":[{"fix":"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.","message":"Bloom filters are probabilistic data structures that can produce 'false positives'. A result of `true` from a membership test means the item *might* be in the set, but it is not a guarantee. A result of `false` means the item is *definitely not* in the set. This characteristic is fundamental to their space efficiency.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"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`.","message":"The library explicitly states it does not expose a CDN for security reasons. Developers including this library in web applications without a module bundler must manually copy the script files from the `web-scripts` directory in the package or GitHub repository and include them via a `<script>` tag.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"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.","message":"Ethereum's use of bloom filters for `logBlooms` is primarily for events (logs), not for standard ETH transactions. Pure ETH transfers do not emit logs and therefore will not be reflected in a block's bloom filter. Contracts must emit events for their data to be queryable via bloom filters.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"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.","message":"The Ethereum protocol itself is moving towards deprecating and eventually removing bloom filters from block headers and transaction receipts, as described in EIP-7668. While this library will continue to function for existing historical blocks that include blooms, new blocks in a post-EIP-7668 Ethereum will have empty bloom filters.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"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.","cause":"Attempting to use CommonJS `require()` syntax in an environment that only supports ES Modules (e.g., Node.js with `\"type\": \"module\"` or modern browsers without a bundler).","error":"ReferenceError: require is not defined"},{"fix":"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';`.","cause":"This error typically occurs if `ethereumBloomFilters` was assigned the result of a `require()` call, but the functions are being accessed incorrectly, or if the global variable isn't properly loaded in a browser context.","error":"TypeError: ethereumBloomFilters.isBloom is not a function"},{"fix":"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.","cause":"This happens when using ES Module `import` syntax but the module is fundamentally CommonJS-only or the bundler/runtime is misinterpreting the export map.","error":"SyntaxError: Named export 'isBloom' not found"}],"ecosystem":"npm"}