eth-rpc-cache

library2.1.0jsnpmunverified

A simple cache for Ethereum RPC requests that wraps provider.send() with caching strategies. Version 2.1.0 is the latest stable release, with no breaking changes in the 2.x line. It supports extensible caching strategies (default: per-block and permanent), optional custom cache store, and strict mode to allow or disallow unknown RPC methods. Ships TypeScript types. Requires Node >=18.

blockchain

npm install eth-rpc-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ETH-RPC-CACHE

eth-rpc-cache

blockchainjavascriptv2.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createEthRpcCache

✓ import { createEthRpcCache } from 'eth-rpc-cache'

✗ import createEthRpcCache from 'eth-rpc-cache'

Named export, not default.

PermanentStrategy

✓ import { PermanentStrategy } from 'eth-rpc-cache'

✗ const { PermanentStrategy } = require('eth-rpc-cache')

ESM import is preferred; CJS require works but may cause issues in mixed environments.

PerBlockStrategy

✓ import { PerBlockStrategy } from 'eth-rpc-cache'

Named export; used in custom strategy arrays.

Creates a cached JSON-RPC provider using ethers.js, caching eth_chainId permanently and eth_blockNumber per block.

import { createEthRpcCache } from 'eth-rpc-cache'; import { providers } from 'ethers'; const provider = new providers.JsonRpcProvider(process.env.RPC_URL ?? 'https://mainnet.infura.io/v3/YOUR-PROJECT-ID'); const cache = new Map(); const cachedProvider = { ...provider, send: createEthRpcCache( (method, params) => provider.send(method, params), { cache } ) }; Object.setPrototypeOf(cachedProvider, Object.getPrototypeOf(provider)); // First call hits RPC const chainId = await cachedProvider.send('eth_chainId', []); console.log(chainId); // Subsequent calls from cache const chainIdAgain = await cachedProvider.send('eth_chainId', []); console.log(chainIdAgain);

Debug

Known issues

gotchaObject.setPrototypeOf is required after spreading provider to maintain correct prototype chain

fix

Add Object.setPrototypeOf(cachedProvider, Object.getPrototypeOf(provider)) after spreading the provider object.

affects: >=1.0.0

breakingv2.0.0 changed from default export to named export createEthRpcCache

fix

Replace `import ethRpcCache from 'eth-rpc-cache'` with `import { createEthRpcCache } from 'eth-rpc-cache'`.

affects: >=2.0.0

gotchaThe default strategy array includes permanentStrategy which caches eth_chainId permanently; ensure cache is cleared if chain changes

fix

Provide a custom strategy array that does not include permanentStrategy, or delete cache entries manually.

affects: >=1.0.0

deprecatedoptions.allowOthers default changed from false to true in v2.0.0

fix

Set allowOthers: false to block unknown methods if needed.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'send')

The spread operator on a provider object does not copy the prototype, so send method is missing.

fix

After spreading, call Object.setPrototypeOf(cachedProvider, Object.getPrototypeOf(provider)).

Module not found: Error: Can't resolve 'eth-rpc-cache'

Package not installed or import path incorrect.

fix

Run `npm install eth-rpc-cache` and use correct import: `import { createEthRpcCache } from 'eth-rpc-cache'`.

Error: Method eth_unknown is not allowed

The default strategy (or options) disallows unknown RPC methods when allowOthers is false.

fix

Set `allowOthers: true` in options, or add a strategy for that method.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

ethersoptionalUsed in examples to create a provider; not a hard dependency but typically used together

Agent activity

32 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bloq/eth-packages ↗

packageeth-rpc-cache ↗

homepagehttps://github.com/bloq/eth-packages#readme ↗