Summary

• Clarify that on child frame failure, execution_state_gas_used is restored to the parent's reservoir and not accumulated into the parent's counter
• Clarify that on top-level exceptional halt, execution_state_gas_used is not reset and still counts toward block_state_gas_used
• Rename "Revert behavior for state gas" → "State gas on frame failure" and reconcile with the reservoir model description

Motivation

The current text has two statements that appear contradictory:

1. Reservoir model (bullet 5): "State gas is fully preserved on failure because state changes are reverted, so no state was actually grown"
2. Revert behavior section: "State gas charged for account creation... is consumed even if the frame reverts — state changes are rolled back but gas is not refunded"

Both are correct but apply to different scopes — (1) describes child frame behavior where state gas is returned to the parent's reservoir, while (2) describes the top-level perspective where consumed state gas has no parent to reclaim it. This distinction was not explicit, causing implementer confusion about whether initcode state gas should count in block_state_gas_used when a CREATE transaction fails at code deposit.

Discovered during bal-devnet-3 testing where a nethermind chain split was traced to this ambiguity.

Line-by-line explanation

Change 1: Bullet 5 (child frame behavior)

Old:

On child success, the remaining state_gas_reservoir is returned to the parent.

New:

On child success, the remaining state_gas_reservoir is returned to the parent and the child's execution_state_gas_used is accumulated into the parent's counter.

The original only mentioned the reservoir being returned on success. It didn't say what happens to execution_state_gas_used. Added: the parent adopts the child's state gas usage counter (EELS: incorporate_child_on_success does evm.state_gas_used += child_evm.state_gas_used).

Old:

...is restored to the parent's reservoir.

New:

...is restored to the parent's state_gas_reservoir; the child's execution_state_gas_used is not accumulated into the parent's counter, because state changes are rolled back and no state was actually grown.

This is the key addition. The original said state gas is "restored to the parent's reservoir" but never mentioned execution_state_gas_used. An implementer reading this could think: the reservoir is restored AND the used counter is accumulated (like the success path). The new text explicitly says the used counter is NOT accumulated — the parent doesn't inherit the child's state gas consumption on failure.

Old:

State gas is fully preserved on failure because state changes are reverted, so no state was actually grown.

Removed. This sentence was the main source of confusion. "Fully preserved" could mean the used counter is preserved (i.e., still counted), when the actual intent is that the gas is preserved in the sense of being returned to the parent's reservoir. The same meaning is now conveyed by the explicit "not accumulated" language above.

Change 2: Bullet 6 (top-level behavior)

Old:

On exceptional halt, remaining gas_left...

New:

On exceptional halt at the top level (no parent frame), remaining gas_left...

The original didn't specify this was about the top level. Since bullet 5 also discusses exceptional halt (child frames), a reader could think this bullet applies to all frames. Added "at the top level (no parent frame)" to make the scope unambiguous.

Old:

The state_gas_reservoir is not consumed, it is returned to the parent frame or preserved at the top level for refund, consistent with the principle that state gas pays for long-term state growth which does not occur on failure.

New:

The state_gas_reservoir is preserved (not consumed) for the sender refund calculation. Unlike child frames, execution_state_gas_used is not reset at the top level and still counts toward block_state_gas_used, because there is no parent frame to absorb the refund.

The original said "returned to parent frame or preserved at top level for refund" — mixing child and top-level behavior in one sentence. But they behave differently: child frames return everything (reservoir + used) to the parent; top level only preserves the reservoir. The new text focuses on the top level only (child is covered in bullet 5) and explicitly states the critical difference: execution_state_gas_used is NOT reset, so it counts in block accounting. This is the exact behavior that caused the Nethermind chain split.

Change 3: Section rename and rewrite

Old title: "Revert behavior for state gas"
New title: "State gas on frame failure"

The old title implied this only covers REVERT. It actually covers both revert and exceptional halt, so the broader name is more accurate.

Old:

State gas charged for account creation... is consumed even if the frame reverts — state changes are rolled back but gas is not refunded.

New:

State gas is deducted at the point of the operation... If the frame subsequently reverts or halts, the deduction is not undone within that frame — but the parent reclaims the child's consumed state gas via the reservoir restoration described above. At the top level, consumed state gas has no parent to reclaim it and counts toward block_state_gas_used.

The old text said "gas is not refunded" — full stop. But for child frames, the gas IS refunded (to the parent's reservoir). The contradiction confused implementers. The new text explains both cases:

1. Within the frame: deduction stands (not undone)
2. At the parent: child's state gas is reclaimed via reservoir restoration
3. At the top level: no parent to reclaim → counts in block

This resolves the apparent contradiction without changing actual behavior.

🤖 Generated with Claude Code