Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createFilterMiddleware
✓ import { createFilterMiddleware } from '@metamask/eth-json-rpc-filters'
✗ const createFilterMiddleware = require('@metamask/eth-json-rpc-filters')
ESM-only since v7; also exported as default.
default
✓ import createFilterMiddleware from '@metamask/eth-json-rpc-filters'
✗ const createFilterMiddleware = require('eth-json-rpc-filters')
Default export is same as named. Package renamed from eth-json-rpc-filters to @metamask/eth-json-rpc-filters in v7.
destroy
✓ const middleware = createFilterMiddleware({...}); middleware.destroy()
destroy is a method on returned middleware, not a separate import.
Create filter middleware, attach to json-rpc-engine, and destroy when done.
import { createFilterMiddleware } from '@metamask/eth-json-rpc-filters';
import { JsonRpcEngine } from '@metamask/json-rpc-engine';
import EthQuery from '@metamask/eth-query';
import PollingBlockTracker from '@metamask/eth-block-tracker';
const provider = { // Example EIP-1193 provider
request: async ({ method, params }) => {
// In real usage, connect to Ethereum node
return {};
}
};
const blockTracker = new PollingBlockTracker({ provider });
const engine = new JsonRpcEngine();
const filterMiddleware = createFilterMiddleware({ blockTracker, provider });
engine.push(filterMiddleware);
// Use engine.handle to process filter RPC requests
// When done:
filterMiddleware.destroy(); // Clean up block tracker listener
Debug
Known issues
breakingPackage renamed from eth-json-rpc-filters to @metamask/eth-json-rpc-filters in v7.0.0. Old import paths break.fixUpdate imports to use @metamask/eth-json-rpc-filters.
affects: <7.0.0
breakingMinimum Node.js version raised to v14 in v5.0.0, then to v16 in v7.0.0, and dropped v16/v21 in v8.0.0.fixUse Node.js >=14.0.0 (v6+) or >=16.0.0 (v7) or >=18.0.0 (v8+).
affects: <5.0.0 || <7.0.0 || <8.0.0
breakingIn v9.0.0, provider interface changed: 'sendAsync' is replaced with 'request' method per EIP-1193.fixEnsure provider object has a 'request' method instead of 'sendAsync'.
affects: >=9.0.0
breakingIn v6.0.0, block filter middleware no longer throws an error if a block is not found.fixHandle missing blocks gracefully; downstream code relying on errors will break.
affects: >=6.0.0
Errors
Common errors & fixes
Cannot find module 'eth-json-rpc-filters'
Package renamed to @metamask/eth-json-rpc-filters in v7.
fixnpm install @metamask/eth-json-rpc-filters and update imports.
TypeError: provider.sendAsync is not a function
v9+ expects EIP-1193 request method, not sendAsync.
fixUse a provider with a request method, e.g., window.ethereum.request.
Error: Block not found
Using v5.x where missing blocks cause errors.
fixUpgrade to v6+ where missing blocks are handled gracefully.
Audit
Dependencies
@metamask/json-rpc-enginerequiredPeer dependency for middleware interface
@metamask/eth-block-trackerrequiredPowers block tracking for filters
@metamask/eth-queryrequiredProvider communication