docs: correct the v0.8.0 insufficient-balance RPC error-text matrix

[osr21]

Summary

The v0.8.0 [Format] entry describing the insufficient-balance JSON-RPC error-text change (in both BREAKING_CHANGES.md and CHANGELOG.md) doesn't match the behavior observable on Arc Testnet post-upgrade on two points, and omits a string collision that tooling authors need to know about. Since the entry's explicit audience is "tooling that matches JSON-RPC error text", the details matter — a matcher updated to follow the current wording breaks on the most common request shape.

All claims below were verified against rpc.testnet.arc.network (post-v0.8.0) on 2026-08-29, and each one is also consistent with this repo's own localdev test expectations.

1. The previous insufficient funds… text is still live — on the most common request shape

The entry says value-exceeds-balance errors "now reflect revm 38's OutOfFunds variant". Measured:

Request shape (eth_estimateGas / eth_call, value > balance)	Error
gasPrice or maxFeePerGas present	-32003 insufficient funds for gas * price + value: have 0 want 1000000000000000000
no fee fields	-32003 EVM error: OutOfFunds

ethers and viem populate fee fields automatically, so most real traffic still gets the previous text. A tooling author who follows the current entry and replaces their insufficient funds pattern with OutOfFunds breaks. The localdev suite already expects both: tests/localdev/evm_compatibility.test.ts asserts /OutOfFunds|insufficient funds/ on this path.

2. gas required exceeds allowance fires on contract/precompile targets — plain EOA-to-EOA transfers never surface it

The entry attributes the new gas required exceeds allowance text to "simple (EOA-to-EOA) transfer with insufficient balance". Measured, with fee fields present:

Case	Result
EOA → EOA, balance ≥ value, zero gas headroom (value = entire balance)	succeeds (0x5208)
EOA → EOA, value > balance	insufficient funds for gas * price + value…
EOA → precompile/contract, balance cannot cover gas	-32000 gas required exceeds allowance (0)

This is exactly what the disable_fee_charge mechanism the entry describes implies: the basic-transfer shortcut bypasses the caller gas-allowance cap, so EOA-to-EOA estimation now succeeds regardless of gas affordability — the allowance error is reachable only on non-shortcut (contract/precompile) targets. The localdev test agrees: the balance check if gas price is provided case deliberately targets a contract "to skip Reth's basic-transfer shortcut" before expecting /insufficient funds for transfer|gas required exceeds allowance/.

3. The allowance string is shared with --rpc.gascap clamping

gas required exceeds allowance (<limit>) is the same string emitted when estimation is clamped by --rpc.gascap — only the parenthesized bound distinguishes a balance-derived allowance from the configured cap. Worth one line here since this is the entry tooling authors will read when their matchers break; it also covers part of the "document how a developer can recognize the RPC-cap error specifically" request in #271.

Changes

• BREAKING_CHANGES.md: rewrote the three sub-bullets of the v0.8.0 [Format] entry to state the request-shape-dependent text matrix, the correct target class for the allowance error, and the --rpc.gascap string collision.
• CHANGELOG.md: mirrored the same corrections in the corresponding one-paragraph bullet.

No taxonomy changes (that discussion belongs to #270) and no new files — this only makes the existing entry match observable behavior.

Context

Surfaced while working through the error-classification discussion in #203, where a downstream SDK consumer's matcher broke on exactly this upgrade. Related: #270 (application-facing breaking-change taxonomy), #271 (RPC gas cap vs protocol limits distinction).

Happy to adjust wording if maintainers prefer to keep the mechanism explanation (disable_fee_charge) out of the operator-facing doc.