Hardhat eth_getLogs: Unbounded block range causes memory exhaustion

Direct Answer

Hardhat does not enforce a documented implicit maximum block range for eth_getLogs. The ethers.js provider passes fromBlock and toBlock directly to the node without built-in pagination or range clamping. There is no official Hardhat plugin or ethers.js helper that automatically paginates these calls. The recommended approach is to manually split the range into smaller chunks, query each chunk separately, and aggregate the results.

Why Unbounded Ranges Fail

A single eth_getLogs request spanning thousands of blocks forces the node to scan every block in that interval, collect matching log entries, serialize the full array, and transmit it over JSON-RPC. On a local Hardhat node, heap memory consumption scales with the number of logs returned. A range covering millions of blocks can produce a payload large enough to trigger out-of-memory conditions or client-side serialization bottlenecks before the response is fully parsed.

Confirmed Behavior vs. Practical Limits

Confirmed: Hardhat's JSON-RPC layer does not add a default block-range cap or automatic pagination for eth_getLogs. The parameters are forwarded as supplied.

Likely and version-dependent: The exact memory ceiling depends on the Node.js heap allocation, the Hardhat Network version, and whether the node runs in-process or as a standalone process. Because these thresholds are not part of a stable API contract, treat any specific block count as a heuristic rather than a guaranteed limit.

Safe Querying Strategy

1. Choose a conservative chunk size. Start with intervals of roughly 1,000–2,000 blocks. Smaller chunks reduce peak memory and make timeouts easier to diagnose.
2. Iterate with bounds. Loop from the deployment block to the latest block, advancing by the chunk size. Clamp the upper bound so you do not overshoot the head block.
3. Add timeout and error handling. Wrap each chunk in a timeout. If a chunk fails or times out, halve the interval and retry rather than aborting the entire scan.
4. Aggregate incrementally. Append results to a list or stream them to disk. Avoid holding the entire multi-year dataset in a single in-memory array if the total log count is large.

Verification

Because Hardhat and ethers.js evolve, verify against your installed versions. Check their changelogs for any added getLogs pagination options or default range caps. To validate locally, run a chunked query against a Hardhat node and monitor process.memoryUsage(); compare the footprint against a single wide-range call to confirm the mitigation works in your environment.