docs: classify JSON-RPC breaking changes for application developers

[kutluhaneth46]

Add [RPC] flag and For Application Developers sections in BREAKING_CHANGES.md for v0.7.2 RPC changes. Clarifies rpc.gascap is a node-local simulation limit and documents the gas required exceeds allowance disambiguation. v0.8.0 error-text classification deferred to #291. Fixes #270, fixes #271.

[osr21]

The taxonomy change is a solid implementation of #270, and I verified the two new v0.7.2 [RPC] entries against the code — both check out exactly: --arc.rpc.allow-unprotected-txs with the verbatim error string (crates/evm-node/src/rpc_middleware.rs:70), and the batch cap with default 100 (ARC_RPC_MAX_BATCH_ENTRIES_DEFAULT, rpc_middleware.rs:75) rejected with -32600 (BATCH_TOO_LARGE_ERROR_CODE) before any per-entry handler runs, as claimed. The gascap-vs-protocol-limit clarification also matches what #271 asked for almost verbatim.

Two substantive problems, though:

1. The v0.8.0 "For Application Developers" entry restates error-text claims that #291 (open) corrects with live-RPC verification.

• "Value exceeds balance … now reflects revm 38's OutOfFunds variant" — only for requests without fee fields. Requests that set gasPrice/maxFeePerGas still return the old insufficient funds for gas * price + value: have X want Y text — and ethers/viem populate fee fields automatically, so most tooling keeps seeing the old string. "Must update its patterns" as written points tools the wrong way; they need to match both.
• "Simple (EOA-to-EOA) transfer with insufficient balance … shifted to gas required exceeds allowance" — it's the opposite for that case: reth 2.2 runs these RPC paths with disable_fee_charge, and the basic-transfer shortcut bypasses the caller gas-allowance check entirely, so an EOA-to-EOA transfer whose balance covers value now estimates successfully regardless of gas affordability. The Missing or invalid parameters → gas required exceeds allowance (<limit>) shift applies to contract/precompile targets.

2. A missed fact that directly serves this PR's own #271 story: gas required exceeds allowance (N) is the same string whether the limit came from the sender's balance-derived allowance or from --rpc.gascap clamping — only the parenthesized N disambiguates (N equal to the configured cap ⇒ cap rejection). That's the single most actionable detail for "an estimation failure is not proof the transaction is impossible on-chain." Related: on Circle's public testnet endpoints the observed effective cap is currently 16,777,216 (2²⁴) — tighter than both the 30M repo default and the 30M block limit (#292) — so the v0.7.2 entry's 30M figure shouldn't be read as current public-endpoint behavior.

Coordination note: this PR and #291 edit the same v0.8.0 region of BREAKING_CHANGES.md, so whichever lands second conflicts — and if both landed as-is, the node-operator section would carry the corrected description while the new app-developer section repeats the superseded one for the same error surface. Suggest either basing the v0.8.0 entry here on #291's corrected text, or scoping this PR to the taxonomy + v0.7.2 entries (which stand on their own) and layering the v0.8.0 classification once #291 resolves.

Small nit: Fixes #270 and #271 auto-closes only #270 — GitHub needs a closing keyword per issue (Fixes #270, fixes #271).

[kutluhaneth46]

Thanks for the detailed review — addressed in 9cf3f04:

• Removed the v0.8.0 ### For Application Developers\ section entirely; v0.8.0 error-text classification is deferred to docs: correct the v0.8.0 insufficient-balance RPC error-text matrix #291 to avoid conflicting claims.
• Expanded the v0.7.2 gascap entry with the \gas required exceeds allowance ()\ disambiguation (balance-derived vs --rpc.gascap) and a note that public RPC endpoints may apply a lower effective cap than the repo default.
• PR body updated to \Fixes docs: classify JSON-RPC behavior changes as application-facing breaking changes #270, fixes docs: explicitly distinguish RPC gas cap from protocol transaction gas limits #271.

[osr21]

Verified 9cf3f04 against the diff — all three items check out: the v0.8.0 app-developer section is gone (the patch now touches only the header taxonomy and the v0.7.2 region), the gascap entry carries the (<limit>) disambiguation plus the public-endpoint caveat, and the PR body uses per-issue closing keywords. Duplicating the gascap change across the operator and app-developer sections with a cross-reference also matches the amended audience rule you added to the header. The conflict with #291 is resolved by construction now — nice clean scope.

I also checked the one thing that worried me about moving the disambiguation into a v0.7.2 entry: whether the "same allowance string on both paths" behavior actually holds on the reth lineage v0.7.x pins (v1.11.3), since I had only verified it against v0.8.0/reth 2.2. Result — your hedged wording holds, with one nuance worth knowing:

• Balance-derived clamp → gas required exceeds allowance (N) with N = the balance-derived budget (RpcInvalidTransactionError::GasRequiredExceedsAllowance, emitted when execution fails at the caller-allowance-clamped limit; the variant's doc comment describes exactly this case).
• Cap/limit-driven failures in v1.11.3 mostly surface as a different string: out of gas: gas required exceeds: N (BasicOutOfGas, via the retry-at-block-limit path) or other halt-derived out-of-gas variants. The allowance string with N = cap can still appear (e.g. when intrinsic gas already exceeds the clamped limit).

So in v0.7.2 the exact string varies by failure mode — which "often surfaces as gas required exceeds allowance (<limit>) or an out-of-gas style error" captures correctly — and the compare-N-against-the-cap heuristic is valid on both lineages. The full convergence of cap and balance failures onto the single allowance string is v0.8.0/reth 2.2 behavior, i.e. exactly the material this PR now defers to #291. No text change needed unless you want to add a parenthetical like "(exact string varies by failure mode)".

One operational heads-up: the Rust Integration Tests CI job is currently failing marginally across unrelated branches (#298 — a 7-node test OOMs nondeterministically on the runner). If this docs-only PR goes red on that job once CI is approved, it's almost certainly that, not your change.

[melekes]

nice patch 👍 although again it should probably go into a separate repo with dApp documentation.