docs: clarify EIP-8037 gas accounting

[mattsse]

Document every Vm.Gas field and the gas measurement/snapshot cheatcodes in terms of EIP-8037 regular gas, state gas, reservoir spillover, refunds, and isolation. Explain why frame consumption is neither a transaction receipt nor a sufficient gas-limit estimate, and clarify ordinary accounting on networks without EIP-8037. Regenerate the canonical cheatcode metadata so downstream interfaces inherit the same explanations.

Companion updates: foundry-rs/forge-std#910, foundry-rs/book#2076, and alloy-rs/alloy#4195.

AI assistance: Codex authored the documentation and PR description.

[github-actions]

✅ Changelog found

The deterministic check will validate the changed entry.

[mattsse]

Checked the new text against frame_gas in the cheatcodes inspector, the isolated-transaction reconciliation in crates/evm/evm/src/inspectors/stack.rs, and testdata/paris/cheats/LastCallGas.t.sol; the facts hold. The suggestions are about structure: every field and cheatcode currently leads with two or three things the value is not before saying what it is, and the same warning block is pasted on nine snapshot overloads. Each suggestion keeps the facts, states the definition first, and leaves one link for the rest.

One comment (on snapshotGasLastFrame) is about behaviour in stack.rs, with measured numbers, not wording. After applying, cheatcodes.json needs regenerating, and forge-std#910 should then be regenerated from it rather than hand-synced.

[mattsse]

Same trim as above, plus a behaviour note, because the sentence "Isolated frames with zero net state gas use receipt gas instead" documents a semantics switch rather than a rule. Measured with forge 1.8.1-nightly (2026-09-04), evm_version = "amsterdam", isolation on, one SSTORE target:

frame	gasTotalUsed	gasStateUsed	gasRefunded	snapshotGasLastFrame
setValue(42), creates a slot	28618	97920	0	28618
setValue(0), clears it	28606	0	5721	22885

With state creation the snapshot is pre-refund regular gas with all state gas dropped; without it, it is post-refund receipt gas (28606 − 5721). The switch is stack.rs: set_isolated_snapshot_gas_used(tx_gas_used()) only runs when block_state_gas_used == 0. Historical snapshots are all pre-Amsterdam, where state gas is always zero, so always recording tx_gas_used() for isolated frames preserves them and makes the isolated snapshot the receipt gas in every case. That is a maintainer call (it changes Amsterdam snapshot values for state-creating calls, upward, to what the transaction actually pays), but either way it belongs in code, not in a subordinate clause here.

Suggested change

	/// This scalar snapshot is not the EIP-8037 sum of regular and state gas.
	/// It can include state gas drawn from regular gas, but excludes state gas paid from the reservoir.
	/// Isolated frames with zero net state gas use receipt gas instead.
	/// Use `lastFrameGas` for separate components. See <https://eips.ethereum.org/EIPS/eip-8037>.
	/// Records regular gas only; EIP-8037 state gas paid from the reservoir is excluded. See <https://getfoundry.sh/reference/cheatcodes/gas-snapshots>.

[mattsse]

Applied the definition-first wording and regenerated the canonical metadata. Kept the state-spillover qualification on snapshots: regular-counter consumption can include state gas, so “regular gas only” would hide that distinction. The book now tabulates the isolated positive-state and zero-state cases. I left the suggested runtime change to snapshot settlement out of this documentation PR; it would change existing snapshot values and needs a separate behavior change.

AI assistance: Codex authored this update and reply.