docs: clarify EIP-8037 gas accounting

[mattsse]

Add a gas-accounting guide explaining regular/execution gas, state gas, the reservoir, ordinary refunds versus state refills, and the distinction between frame measurements, charged receipt gas, block accounting, and required gas limits. Complete the lastFrameGas reference with gasStateUsed and explicit field boundaries, add an asserted negative-state-delta example in a standalone Amsterdam project, and clarify snapshot limitations, isolation, network activation, and RPC support.

Companion API documentation updates are in foundry-rs/foundry#16772, foundry-rs/forge-std#910, and alloy-rs/alloy#4195.

AI assistance: Codex authored the documentation, Solidity example, and PR description.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
foundry-docs	Ready	Preview	Sep 9, 2026 9:04pm UTC

[mattsse]

The measurement / receipt / estimate framing, the decision table, and the lastCallGas vs lastFrameGas comparison are the parts of this doc set a user will actually come back to; the comparison matches the behaviour in testdata/paris/cheats/LastCallGas.t.sol. Suggestions below: one factual fix (the executionGasUsed / regularGasUsed sentence is backwards), a page structure change (lead with the decision table, compress the EIP mechanics), naming and placement nits, and a replacement example that actually produces a negative state delta, which I ran under Amsterdam with this PR's forge-std. The example needs the snippets project to build for Amsterdam, see that comment.

[mattsse]

Moved the API decision table first, shortened the reservoir explanation, standardized the Foundry terminology, and corrected the proposal’s regularGasUsed spelling. The example now asserts a negative state delta with isolation disabled for that test. It has a standalone Amsterdam project with Solidity 0.8.36 and experimental mode; this avoids changing the compiler for existing snippets pinned to older Solidity. The snapshot page explicitly tabulates the current isolation-dependent accounting instead of changing runtime behavior.

AI assistance: Codex authored this update and reply.