Ethereum Bloom Filters Client

Common errors

• ReferenceError: require is not defined

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

• TypeError: ethereumBloomFilters.isBloom is not a function

  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.
  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';`.

• SyntaxError: Named export 'isBloom' not found

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

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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`.
• gotcha 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.
  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.
• deprecated 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.
  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.

Install

• npm install ethereum-bloom-filters npm
• yarn add ethereum-bloom-filters yarn
• pnpm add ethereum-bloom-filters pnpm

Imports

• isBloom
  wrong:

  const isBloom = require('ethereum-bloom-filters').isBloom;

  correct:

  import { isBloom } from 'ethereum-bloom-filters';

  Primary usage is with named ESM imports for individual functions. Direct CommonJS `require()` returns an object with all exports.
• ethereumBloomFilters
  wrong:

  import ethereumBloomFilters from 'ethereum-bloom-filters';

  correct:

  const ethereumBloomFilters = require('ethereum-bloom-filters');

  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.
• isUserEthereumAddressInBloom
  wrong:

  ethereumBloomFilters.isUserEthereumAddressInBloom(); // without prior require() or script tag

  correct:

  import { isUserEthereumAddressInBloom } from 'ethereum-bloom-filters';

  Always ensure the library is loaded and assigned to a variable, or use named ESM imports when accessing these utility functions.

Quickstart

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.

import { isUserEthereumAddressInBloom, isTopicInBloom, isInBloom } from 'ethereum-bloom-filters';

// Example Ethereum block bloom (a 256-byte hex string, actual bloom from a real block would be much longer)
const blockBloom = '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000';
// A fake Ethereum address (20 bytes)
const userAddress = '0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B'; 
// A fake topic (32 bytes)
const eventTopic = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';

const isAddressLikelyPresent = isUserEthereumAddressInBloom(blockBloom, userAddress);
const isTopicLikelyPresent = isTopicInBloom(blockBloom, eventTopic);
const isGenericValueLikelyPresent = isInBloom(blockBloom, 'some_arbitrary_value');

console.log(`Is address ${userAddress} likely in bloom? ${isAddressLikelyPresent}`); // Should be false with an empty bloom
console.log(`Is topic ${eventTopic} likely in bloom? ${isTopicLikelyPresent}`);   // Should be false with an empty bloom
console.log(`Is generic value likely in bloom? ${isGenericValueLikelyPresent}`); // Should be false with an empty bloom

// Note: Bloom filters are probabilistic. A 'true' result means it *might* be present (false positive possible).
// A 'false' result means it is *definitely not* present (no false negatives).