docs: explicitly distinguish RPC gas cap from protocol transaction gas limits

[mssystem1]

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.gascap limits 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:

1. RPC simulation gas cap
2. maximum transaction gas constraints
3. 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.

[osr21]

The distinction you're drawing is correct and worth documenting — --rpc.gascap and 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:

1. RPC simulation cap (--rpc.gascap) — a node-local execution-layer flag (Reth/geth lineage). It only bounds the gas allowance handed to eth_call, eth_estimateGas, and eth_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.gascap setting. It never touches an actually-submitted transaction.
2. Per-transaction / protocol gas constraints — enforced by the protocol when a tx is included. Independent of any RPC flag.
3. Block gas limit — the header gasLimit, enforced at block production/validation. Also independent of --rpc.gascap.

So a call hitting --rpc.gascap 30000000 says "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_estimateGas surfaces 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)" — the 30000000 being 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:

• Documentation (low-risk, do this now): the note you proposed is good. I'd also add the observable error shape so developers can pattern-match today: the message includes the numeric cap (... allowance (30000000)), whereas a genuine revert carries execution reverted (optionally with revert data). Documenting "if the failing estimate's message names your node's --rpc.gascap value, raise the cap or split the call — the transaction is not necessarily unexecutable" would resolve most of the confusion without any code change.
• Machine-detectable distinct error (higher-risk, flag as a separate discussion): introducing an Arc-specific error code or structured data field 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.