fix: honor gas limit in eth_estimateGas

[LesnyRumcajs]

Summary of changes

Changes introduced in this pull request:

• honor gas limit in eth_estimateGas
• align some of the gas estimate behavior with reth - the behavior in some cases is different than in Lotus but it should be more usable - eth_* consumers are mostly tuned for reth and geth

Reference issue to close (if applicable)

Closes #7702

Other information and links

AI summary on the behavior between different clients

Scenario	Forest before ([v0.37.0], [f7236f6][forest-main])	Forest after (this PR)	geth [v1.17.7][geth]	reth [v2.7.0][reth]	Lotus master [99e2be2][lotus] (unreleased, [#13865])
No gas given	normal estimate; a gas-dependent revert is 3 gas search failed: message execution failed (...)	same estimate; the revert is 3 without the gas search failed: prefix	normal estimate	normal estimate	same as Forest after
Call fits within N	estimate, N ignored (can exceed N)	estimate ≤ N	estimate ≤ N	estimate ≤ N	normal estimate if ≤ N, otherwise N after a successful run at N
N below the intrinsic gas / message inclusion cost	estimate, N ignored	-32000 gas required exceeds allowance (N)	N < 21000: N ignored, estimate; otherwise -32000 gas required exceeds allowance (N)	-32000 gas required exceeds allowance (N)	2 call ran out of gas
Out of gas within N	estimate, N ignored	-32003 out of gas: gas required exceeds: N	-32000 gas required exceeds allowance (N)	-32003 out of gas: gas required exceeds: N	2 call ran out of gas (3 if a contract catches the inner out-of-gas and reverts)
Reverts within N, succeeds with more gas (e.g. require(gasleft() > X))	3 gas search failed: message execution failed (...)	-32003 out of gas: gas required exceeds: N	3 execution reverted[: reason]	-32003 out of gas: gas required exceeds: N	3 message execution failed (...)
Same, with N high enough	3 with the prefix (never searched)	estimate ≤ N (searched past the revert)	estimate ≤ N	estimate ≤ N	3 (never searched)
Reverts at any gas	3 message execution failed (...)	3 message execution failed (...)	3 execution reverted[: reason]	3 execution reverted[: reason]	3 message execution failed (...)
Out of gas even at the block gas limit	2 call ran out of gas; contract or non-existent sender: 3 with exit=[SysErrOutOfGas(7)]	-32003 out of gas: gas required exceeds: N	-32000 gas required exceeds allowance (N)	-32003 out of gas: gas required exceeds: N	1 failed to estimate gas: call ran out of gas; contract or non-existent sender: 3 with exit=[SysErrOutOfGas(7)]
Sender cannot pay the gas fee at higher limits	estimated fees apply: ~1.25 × block gas limit if higher limits are unaffordable; 3 with the prefix and exit=[SysErrSenderStateInvalid(2)] if even the estimate is	fees ignored (the capped search runs with zero fees); value must still be covered	no gas price: fees ignored, value still checked (-32000 insufficient funds for gas * price + value); with a gas price: the ceiling is capped at (balance - value) / feeCap	no gas price: fees ignored; with a gas price: the ceiling is capped at the caller's allowance	estimated fees apply: 3 with exit=[SysErrSenderStateInvalid(2)] (2 if N is below the inclusion cost)

Change checklist

• I have performed a self-review of my own code,
• I have made corresponding changes to the documentation. All new code adheres to the team's documentation standards,
• I have added tests that prove my fix is effective or that my feature works (if possible),
• I have made sure the CHANGELOG is up-to-date. All user-facing changes should be reflected in this document.

Outside contributions

• This pull request is based on an issue that a maintainer has accepted (see Before Opening a Pull Request).
• I have read and agree to the CONTRIBUTING document.
• I have read and agree to the AI Policy document. I understand that failure to comply with the guidelines will lead to rejection of the pull request.

Summary by CodeRabbit

• Bug Fixes
  • eth_estimateGas now honors a transaction’s supplied gas limit, capped at the block gas limit, when calculating estimates.
  • Calls that exceed the supplied limit return a specific error. Calls with no gas limit continue to use the previous estimation behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Essentials
• Run ID: 8ddea5e2-43bd-48fb-a8f8-ef9726bec135

📥 Commits

Reviewing files that changed from the base of the PR and between 1b7c2eb and a6cd9ba.

📒 Files selected for processing (8)

• CHANGELOG.md
• src/dev/subcommands/devnet_cmd/eth_gas.rs
• src/dev/subcommands/devnet_cmd/eth_skip_sender.rs
• src/dev/subcommands/tests_cmd/helpers.rs
• src/rpc/methods/eth.rs
• src/rpc/methods/eth/errors.rs
• src/rpc/methods/eth/types.rs
• src/rpc/methods/gas.rs

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• filecoin-project/lotus (manual)

💤 Files with no reviewable changes (1)

• src/dev/subcommands/devnet_cmd/eth_skip_sender.rs

Included review availability: This review used your included allowance. 4 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

---

Walkthrough

eth_estimateGas now uses a supplied gas value as an upper bound, capped at the block gas limit. It returns distinct JSON-RPC errors when the allowance is below message inclusion cost or execution needs more gas. Calls without gas retain the previous estimation behavior.

Changes

Gas-capped estimation

Layer / File(s)	Summary
Gas cap and error contracts src/rpc/methods/eth/types.rs, src/rpc/methods/eth/errors.rs	EthCallMessage provides a normalized gas cap. EthErrors adds cap-specific errors, RPC codes, messages, and conversion from apply results.
Capped gas search src/rpc/methods/eth.rs, src/rpc/methods/gas.rs	Estimation passes the cap through sender-validation and gas-search paths. Search limits probes to the cap and classifies failed probes. Fee-free message setup is shared through without_fees.
Capped estimation tests and support src/rpc/methods/eth.rs, src/dev/subcommands/devnet_cmd/eth_gas.rs, src/dev/subcommands/devnet_cmd/eth_skip_sender.rs, src/dev/subcommands/tests_cmd/helpers.rs, CHANGELOG.md	RPC and devnet tests cover capped estimates and error mapping. The devnet tests use a shared JSON-RPC error extractor. The changelog records the behavior.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant eth_estimate_gas
  participant eth_gas_search
  participant gas_search
  Caller->>eth_estimate_gas: Submit call with optional gas
  eth_estimate_gas->>eth_gas_search: Pass message and gas cap
  eth_gas_search->>gas_search: Search up to the cap
  gas_search-->>eth_gas_search: Return estimate or cap-specific error
  eth_gas_search-->>Caller: Return estimate or error

Loading

Merge Risk: ⚪ Minimal · up to a6cd9

eth_estimateGas now honors the supplied gas limit as an upper bound and returns distinct errors when the limit is insufficient. No actionable merge-blocking risk remains after review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 76.09% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 46 functions across 6 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: honoring the gas limit in eth_estimateGas.
Linked Issues check	✅ Passed	Issue #7702 asks eth_estimateGas to honor the caller’s gas limit. EthCallMessage::gas_cap applies the supplied nonzero cap up to BLOCK_GAS_LIMIT, and message conversion uses that cap. The adde…
Out of Scope Changes check	✅ Passed	The changelog entry, gas-limit error mapping, fee-free estimation helper, and regression tests support the #7702 behavior. Moving rpc_call_err into shared test helpers supports the new JSON-RPC erro…

Full details: Docstring Coverage

Explanation

Docstring coverage is 76.09% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 46 functions across 6 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

✨ Simplify code

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

🔧 Clippy (1.98.1)

Clippy execution failed

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 29.46058% with 170 lines in your changes missing coverage. Please review.
✅ Project coverage is 67.51%. Comparing base (1b7c2eb) to head (a6cd9ba).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/dev/subcommands/devnet_cmd/eth_gas.rs	0.00%	112 Missing ⚠️
src/rpc/methods/eth.rs	37.34%	50 Missing and 2 partials ⚠️
src/dev/subcommands/tests_cmd/helpers.rs	0.00%	5 Missing ⚠️
src/rpc/methods/gas.rs	88.88%	1 Missing ⚠️

Additional details and impacted files

Files with missing lines	Coverage Δ
src/dev/subcommands/devnet_cmd/eth_skip_sender.rs	0.00% <ø> (ø)
src/rpc/methods/eth/errors.rs	100.00% <100.00%> (+1.62%)	⬆️
src/rpc/methods/eth/types.rs	68.46% <100.00%> (+0.63%)	⬆️
src/rpc/methods/gas.rs	88.83% <88.88%> (+1.36%)	⬆️
src/dev/subcommands/tests_cmd/helpers.rs	0.00% <0.00%> (ø)
src/rpc/methods/eth.rs	71.96% <37.34%> (-0.21%)	⬇️
src/dev/subcommands/devnet_cmd/eth_gas.rs	0.00% <0.00%> (ø)

... and 10 files with indirect coverage changes

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1b7c2eb...a6cd9ba. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.