Repository navigation
docs: explicitly distinguish RPC gas cap from protocol transaction gas limits #271
Description
Summary
Arc's breaking-change documentation describes the --rpc.gascap default being reduced from 50,000,000 to 30,000,000.
The documentation correctly explains that eth_call and eth_estimateGas requests requiring more than the configured cap can fail.
However, it would be useful to explicitly state that the RPC gas cap is an RPC simulation/execution limit and should not automatically be interpreted as the protocol's maximum executable transaction gas limit.
Problem
Developers frequently use eth_estimateGas to determine whether a transaction is executable.
If:
eth_estimateGas -> fails because RPC gas cap was reached
it is easy to incorrectly interpret the result as:
transaction cannot be executed by Arc
Those are not necessarily equivalent conditions.
A node-local RPC limit can reject simulation before the protocol itself would reject the transaction.
Expected Documentation
The breaking-change entry should explicitly explain the distinction.
For example:
Note:
--rpc.gascaplimits gas available to applicable JSON-RPC
simulation calls. Reaching this limit does not necessarily mean the
corresponding transaction exceeds Arc's protocol-level transaction or
block gas limits.
It would also be useful to document the error returned when this specific limit is reached.
Why This Matters
Libraries and applications often treat gas-estimation failures as transaction failures.
Examples include:
- ethers
- viem
- wagmi
- Hardhat
- Foundry scripts
- wallets
- account abstraction infrastructure
Without distinguishing a node-local simulation limit from a protocol rejection, developers may unnecessarily modify contracts or assume a transaction is impossible.
Suggested Fix
Document three separate concepts where applicable:
- RPC simulation gas cap
- maximum transaction gas constraints
- block gas constraints
Also document how a developer can recognize the RPC-cap error specifically.
Optional Improvement
Expose enough information in the RPC error to make the condition machine-detectable.
For example, applications should ideally be able to distinguish:
simulation exceeded RPC gas cap
From:
execution reverted
And:
transaction exceeds protocol gas limit
without parsing ambiguous error strings.
Activity
osr21 commentedon Aug 17, 2026
The distinction you're drawing is correct and worth documenting —
--rpc.gascapand the protocol/block gas limits are three different mechanisms enforced at different layers, and conflating them does lead to exactly the false "transaction is impossible" conclusion you describe.The three limits, and where each is enforced:
--rpc.gascap) — a node-local execution-layer flag (Reth/geth lineage). It only bounds the gas allowance handed toeth_call,eth_estimateGas, andeth_createAccessList. It is configuration, not consensus: two Arc nodes on the same chain can return different results for the same call purely because of their--rpc.gascapsetting. It never touches an actually-submitted transaction.gasLimit, enforced at block production/validation. Also independent of--rpc.gascap.So a call hitting
--rpc.gascap 30000000says "this node refused to simulate above 30M gas", not "Arc cannot execute this transaction" — the same tx could estimate fine against a node running--rpc.gascap 50000000, and could be includable if it's within the actual block gas limit. Your point (1)/(2)/(3) framing captures this cleanly.On making the condition machine-detectable — this is the hard part, and worth setting expectations in the doc. The gas-cap rejection is raised by the upstream Reth EL, and in the geth/reth lineage
eth_estimateGassurfaces a cap overshoot as a generic JSON-RPC server error (-32000) with a human-readable string along the lines of "gas required exceeds allowance (30000000)" — the30000000being the configured cap. There is no distinct, standardized error code separating "exceeded RPC gas cap" from "execution reverted" from "exceeds protocol gas limit"; all three land as-32000+ differing message text. That's precisely why ethers/viem/wagmi/Foundry collapse them into a single estimation failure.Two implications for the fix:
... allowance (30000000)), whereas a genuine revert carriesexecution reverted(optionally with revert data). Documenting "if the failing estimate's message names your node's--rpc.gascapvalue, raise the cap or split the call — the transaction is not necessarily unexecutable" would resolve most of the confusion without any code change.datafield to disambiguate would diverge from geth/reth conventions, and the tooling you list keys off the standard-32000/string shape — a custom code risks being dropped or mishandled by those clients rather than helping. If pursued, it likely belongs upstream in Reth (so the whole ecosystem benefits) rather than as an Arc fork behavior. I'd keep the docs fix and the error-shape change as two separate items so the useful, safe part isn't blocked on the contentious part.Net: the docs clarification (three-limit distinction + the cap error's recognizable shape) is clearly worth landing. I'd scope this issue to that, and split the "expose a distinct machine-readable error" idea into its own tracking issue since it's an upstream-Reth / API-compatibility decision. Happy to draft the doc paragraph as a PR against
BREAKING_CHANGES.md(and/or the RPC docs) if a maintainer wants it.kutluhaneth46 commentedon Aug 31, 2026
Addressed in the same PR as #270.
kutluhaneth46 commentedon Sep 1, 2026
Opened #308 with the three-limit distinction + EIP-7825 framing osr21 outlined — For Application Developers section in BREAKING_CHANGES v0.7.2.
kutluhaneth46 commentedon Sep 10, 2026
@huklaa Already covered by open PR #308. Review comments welcome on that thread rather than a duplicate PR.