@metamask/eth-json-rpc-filters

6.0.1 verified Sat Apr 25 auth: no javascript

Implementation of Ethereum JSON-RPC filter methods (eth_newFilter, eth_newBlockFilter, eth_newPendingTransactionFilter, eth_uninstallFilter, eth_getFilterChanges, eth_getFilterLogs) as middleware for json-rpc-engine. Current stable version: 9.0.0. Uses eth-block-tracker for block polling and requires an EIP-1193 provider. Key differentiator: specifically designed for MetaMask's architecture, wrapping web3 providers into filter middleware. Supports Node.js >=14.0.0. v7.0.0 renamed from eth-json-rpc-filters to @metamask/eth-json-rpc-filters and dropped Node.js <16.

Common errors

error Cannot find module 'eth-json-rpc-filters' ↓

cause Package renamed to @metamask/eth-json-rpc-filters in v7.

fix

npm install @metamask/eth-json-rpc-filters and update imports.

error TypeError: provider.sendAsync is not a function ↓

cause v9+ expects EIP-1193 request method, not sendAsync.

fix

Use a provider with a request method, e.g., window.ethereum.request.

error Error: Block not found ↓

cause Using v5.x where missing blocks cause errors.

fix

Upgrade to v6+ where missing blocks are handled gracefully.

Warnings

breaking Package renamed from eth-json-rpc-filters to @metamask/eth-json-rpc-filters in v7.0.0. Old import paths break. ↓

fix Update imports to use @metamask/eth-json-rpc-filters.

breaking Minimum 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. ↓

fix Use Node.js >=14.0.0 (v6+) or >=16.0.0 (v7) or >=18.0.0 (v8+).

breaking In v9.0.0, provider interface changed: 'sendAsync' is replaced with 'request' method per EIP-1193. ↓

fix Ensure provider object has a 'request' method instead of 'sendAsync'.

breaking In v6.0.0, block filter middleware no longer throws an error if a block is not found. ↓

fix Handle missing blocks gracefully; downstream code relying on errors will break.

Install

npm install eth-json-rpc-filters

yarn add eth-json-rpc-filters

pnpm add eth-json-rpc-filters

Imports

createFilterMiddleware

wrong

const createFilterMiddleware = require('@metamask/eth-json-rpc-filters')

correct

import { createFilterMiddleware } from '@metamask/eth-json-rpc-filters'

ESM-only since v7; also exported as default.

default

wrong

const createFilterMiddleware = require('eth-json-rpc-filters')

correct

import createFilterMiddleware from '@metamask/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.

Quickstart

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