refactor(spec-specs): organize gas logic in amsterdam EIP-8037/8038/2780 (#3159)

* refactor(spec-specs, tools): bundle amsterdam frame gas into GasMeter

Gather the flat gas fields on Evm into a GasMeter dataclass in
vm/gas.py and replace the scattered hand-rolled gas arithmetic with
named operations:

- State-gas rollback becomes self-contained on the meter: a
  state_gas_baseline field records the reservoir level a rollback
  refills to (the frame's grant at entry), commit_state_gas folds
  everything consumed since the baseline into state_gas_committed and
  moves the baseline down (zeroing the spill, so post-commit refunds
  route to the reservoir), restore_state_gas refills to the baseline
  on revert or halt, and restore_state_gas_to_entry undoes the commit
  when the transaction rollback also reverts the applied delegations.
  Message.state_gas_reservoir is never mutated after construction.
- Frame lifecycle helpers (refill/commit and credit_state_gas_refund)
  move from vm/__init__.py into vm/gas.py; incorporate_child_on_*
  stay as thin wrappers over the new absorb_child_gas_on_* meter
  operations.
- Inline arithmetic in interpreter.py (burn-all-gas), system.py
  (reservoir handoffs) and fork.py (EIP-8037 split, refund + floor
  settlement) becomes forfeit_remaining_gas, withhold_create_gas,
  drain_state_gas_reservoir, restore_child_gas, allocate_execution_gas
  and settle_transaction_gas; tx_state_gas_used measures the top
  frame's net state gas at settlement.
- t8n tracer protocols gain gas-layout accessors so both the flat and
  gas-meter Evm shapes trace through one code path.

The meter carries no per-frame regular-gas counter: since #3005 the
block's regular-gas dimension is derived from transaction totals
(tx.gas - gas_left - state_gas_left, floor-bound), so a frame-level
counter would only ever be charged, discounted across sub-calls, and
forfeited on halts without being read.

The identifiers avoid "frame" (restore_child_gas, tx_state_gas_used,
withhold_create_gas) ahead of EIP-8141, which will give the term a
protocol meaning.

Behavior-preserving: verified with ruff, mypy, ethereum-spec-lint,
vulture, spec-tools, json_loader tracing on Amsterdam and Osaka, and
the EIP-8037/2780/7778 fill battery.

* refactor(spec-specs): name the gas stages in amsterdam opcodes

Give the two-dimensional gas choreography named stages so structurally
corresponding code sits in structurally corresponding places:

- CALL*/CREATE* wrappers price the opcode in labeled sections --
  GAS (STATE-INDEPENDENT) computes and affordability-checks everything
  that needs no state access, STATE ACCESS (STATE-DEPENDENT GAS)
  performs the accesses and completes the pricing, STATE GAS holds the
  account-creation charge, and CHILD GRANT withholds the child's
  regular share and drains the reservoir in one block.
- generic_call and generic_create reduce to the child-frame lifecycle
  (PREFLIGHT, DESTINATION ACCESS, DISPATCH, OUTCOME): grant
  withholding and all charging move to the wrappers, and the balance
  preflight folds into generic_call via
  GenericCall.insufficient_balance, unifying the abort-without-spawn
  paths.
- The same stage labels apply to sstore and selfdestruct, the two
  other opcodes with state-gas stages; single-stage opcodes keep the
  bare GAS marker.
- Frame-settlement comments on the process_message handlers state the
  postcondition the parent-side absorb relies on.

Behavior-preserving: statement order of every charge, check, and
trace event is unchanged; verified with the EIP-8037/2780/7778 fill
battery and the full static suite.

* refactor(spec-specs): unify amsterdam child-frame incorporation

Discard a failed frame's refunds in restore_state_gas, alongside the
state gas rollback, instead of ignoring them at the absorption sites.
Every settled meter now states exactly what the frame gives back, so
a single incorporate_child replaces the on-success/on-error pair (and
the absorb_child_gas_on_* helpers): gas is absorbed unconditionally,
while logs, self-destructs, and warmed access sets survive only on
success. The top frame's refund read in process_message_call becomes
unconditional for the same reason.

* chore(tooling): document gas handling rules in implement-eip skill

Capture the two-dimensional gas philosophy from the Amsterdam gas
refactors so future sessions do not re-derive it: gas movements are
named GasMeter helpers in vm/gas.py, opcodes price in labeled stages
with all charging before the operation, generic_call/generic_create
run only the child-frame lifecycle, and gas changes are verified by
preserving charge/check/trace order against the fill tests.

* fix static test fails

Author: gurukamath

.claude/commands/implement-eip.md

@@ -28,10 +28,22 @@ Each fork lives at `src/ethereum/forks/<fork_name>/`. Explore the latest fork di
 ## Adding a New Opcode
 
 1. Add to `Ops` enum in `vm/instructions/__init__.py` with hex value
-2. Implement function in appropriate `vm/instructions/<category>.py` — follows pattern: STACK → GAS (`charge_gas`) → OPERATION → PROGRAM COUNTER
+2. Implement function in appropriate `vm/instructions/<category>.py` — follows pattern: STACK → GAS (`charge_gas`) → OPERATION → PROGRAM COUNTER. Opcodes that touch state use the staged gas labels — see "Gas Handling" below.
 3. Register in `op_implementation` dict in `vm/instructions/__init__.py`
 4. Add gas constant in `vm/gas.py` if needed
 
+## Gas Handling
+
+Recent forks meter two gas dimensions: regular gas and state gas (for durable state growth). Key rules:
+
+1. Gas constants and calculations go in `vm/gas.py`; a frame's mutable gas state lives on `Evm.gas_meter`.
+2. Extend the named helper vocabulary (`charge_*`, `credit_*`, `restore_*`, `withhold_*`, ...) instead of doing gas arithmetic by hand at call sites; encode each helper's invariant as an assert.
+3. State gas is charged by the frame whose opcode causes the creation, before the child's regular-gas share is withheld; the whole reservoir passes to the child.
+4. A failing frame settles its own meter before returning, so parents incorporate children unconditionally.
+5. Opcodes that touch state use labeled stages, with all charging before the operation: `GAS (STATE-INDEPENDENT)` → `STATE ACCESS (STATE-DEPENDENT GAS)` → `STATE GAS` → `CHILD GRANT` → `OPERATION`. Simple opcodes keep the bare `GAS` marker. `generic_call`/`generic_create` contain no pricing; they run the child lifecycle: `PREFLIGHT` → `DESTINATION ACCESS` → `CHILD GRANT` → `DISPATCH` → `OUTCOME`.
+6. Avoid "frame" in gas identifiers (a future EIP claims the term); when a name diverges from the spec's variable name, cross-reference the spec name in the docstring.
+7. A gas change is behavior-preserving only if the relative order of every charge, check, and trace event is unchanged; verify with the gas-related fill tests under `tests/<fork>/`.
+
 ## Adding a New Precompile
 
 1. Define address constant in `vm/precompiled_contracts/__init__.py` using `hex_to_address("0x...")`

src/ethereum/forks/amsterdam/fork.py

@@ -103,10 +103,12 @@
 from .vm.gas import (
     GasCosts,
     StateGasCosts,
+    allocate_execution_gas,
     calculate_blob_gas_price,
     calculate_data_fee,
     calculate_excess_blob_gas,
     calculate_total_blob_gas,
+    settle_transaction_gas,
 )
 from .vm.interpreter import MessageCallOutput, process_message_call
 
@@ -1032,8 +1034,6 @@ def process_transaction(
     sender = recover_sender(tx)
     intrinsic = validate_transaction(tx, sender)
 
-    intrinsic_gas = Uint(intrinsic.regular)
-
     (
         effective_gas_price,
         blob_versioned_hashes,
@@ -1055,12 +1055,9 @@ def process_transaction(
 
     effective_gas_fee = tx.gas * effective_gas_price
 
-    # Split execution gas into gas_left (capped by remaining regular gas
-    # budget) and state_gas_reservoir.
-    execution_gas = tx.gas - intrinsic_gas
-    regular_gas_budget = TX_MAX_GAS_LIMIT - intrinsic.regular
-    gas = min(regular_gas_budget, execution_gas)
-    state_gas_reservoir = Uint(execution_gas - gas)
+    # Split execution gas into a regular grant (capped by the remaining
+    # regular-gas budget) and a state gas reservoir.
+    allocation = allocate_execution_gas(tx.gas, intrinsic)
 
     increment_nonce(tx_state, sender)
 
@@ -1087,8 +1084,8 @@ def process_transaction(
         recipient=tx.to,
         value=tx.value,
         gas_price=effective_gas_price,
-        gas=gas,
-        state_gas_reservoir=state_gas_reservoir,
+        gas=allocation.regular_gas,
+        state_gas_reservoir=allocation.state_gas_reservoir,
         access_list_addresses=access_list_addresses,
         access_list_storage_keys=access_list_storage_keys,
         state=tx_state,
@@ -1102,43 +1099,32 @@ def process_transaction(
 
     tx_output = process_message_call(message)
 
-    tx_gas_used_before_refund = (
-        tx.gas - tx_output.gas_left - tx_output.state_gas_left
-    )
-    tx_gas_refund = min(
-        tx_gas_used_before_refund // Uint(5), Uint(tx_output.refund_counter)
+    settlement = settle_transaction_gas(
+        tx.gas,
+        intrinsic,
+        tx_output.gas_left,
+        tx_output.state_gas_left,
+        tx_output.refund_counter,
+        tx_output.state_gas_used,
     )
-    tx_gas_used_after_refund = tx_gas_used_before_refund - tx_gas_refund
 
-    # Transactions with less execution_gas_used than the floor pay at the
-    # floor cost.
-    tx_gas_used = max(tx_gas_used_after_refund, intrinsic.calldata_floor)
-
-    tx_gas_left = tx.gas - tx_gas_used
-    gas_refund_amount = tx_gas_left * effective_gas_price
+    gas_refund_amount = settlement.gas_left * effective_gas_price
 
     # For non-1559 transactions effective_gas_price == tx.gas_price
     priority_fee_per_gas = effective_gas_price - block_env.base_fee_per_gas
-    transaction_fee = tx_gas_used * priority_fee_per_gas
+    transaction_fee = settlement.gas_used * priority_fee_per_gas
 
     # refund gas
     create_ether(tx_state, sender, U256(gas_refund_amount))
 
     # transfer miner fees
     create_ether(tx_state, block_env.coinbase, U256(transaction_fee))
 
-    tx_state_gas = tx_output.state_gas_used
-    # The calldata floor binds the regular-gas dimension: subtract state gas
-    # first so the floor is not discounted by a transaction's state spending.
-    tx_regular_gas = max(
-        tx_gas_used_before_refund - Uint(max(0, tx_state_gas)),
-        intrinsic.calldata_floor,
-    )
-    block_output.block_gas_used += tx_regular_gas
-    block_output.block_state_gas_used += Uint(max(0, tx_state_gas))
+    block_output.block_gas_used += settlement.regular_gas_used
+    block_output.block_state_gas_used += settlement.state_gas_used
     block_output.blob_gas_used += tx_blob_gas_used
 
-    block_output.cumulative_gas_used += tx_gas_used
+    block_output.cumulative_gas_used += settlement.gas_used
     receipt = make_receipt(
         tx, tx_output.error, block_output.cumulative_gas_used, tx_output.logs
     )

src/ethereum/forks/amsterdam/vm/__init__.py

@@ -26,9 +26,10 @@
 
 from ..block_access_lists import BlockAccessList, BlockAccessListBuilder
 from ..blocks import Log, Receipt, Withdrawal
-from ..fork_types import Authorization, StateGas, VersionedHash
+from ..fork_types import Authorization, VersionedHash
 from ..state_tracker import BlockState, TransactionState
 from ..transactions import LegacyTransaction
+from .gas import GasMeter
 
 __all__ = ("Environment", "Evm", "Message")
 TRANSFER_TOPIC = keccak256(b"Transfer(address,address,uint256)")
@@ -170,11 +171,9 @@ class Evm:
     stack: List[U256]
     memory: bytearray
     code: Bytes
-    gas_left: Uint
-    state_gas_left: Uint
+    gas_meter: GasMeter
     valid_jump_destinations: Set[Uint]
     logs: Tuple[Log, ...]
-    refund_counter: int
     running: bool
     message: Message
     output: Bytes
@@ -183,43 +182,21 @@ class Evm:
     error: Optional[EthereumException]
     accessed_addresses: Set[Address]
     accessed_storage_keys: Set[Tuple[Address, Bytes32]]
-    regular_gas_used: Uint = Uint(0)
-    state_gas_spilled: Uint = Uint(0)
-    committed_state_gas: int = 0
-    """
-    State gas locked in by [`commit_frame_state_gas`] because the state
-    it paid for outlives a later failure in the frame.
-
-    [`commit_frame_state_gas`]: ref:ethereum.forks.amsterdam.vm.commit_frame_state_gas
-    """  # noqa: E501
 
 
-def credit_state_gas_refund(evm: Evm, amount: StateGas) -> None:
+def incorporate_child(evm: Evm, child_evm: Evm) -> None:
     """
-    Credit a state gas refund to the local frame, in LIFO order.
-
-    State-gas charges draw from the reservoir first and from `gas_left`
-    last, so refills credit the pool charged last first: `gas_left` up
-    to `state_gas_spilled`, then the reservoir. This restores the
-    exact pools the charge drew from, so the two never drift.
-
-    Parameters
-    ----------
-    evm :
-        The frame crediting the refund.
-    amount :
-        The refund amount to credit.
-
-    """
-    from_gas_left = min(amount, evm.state_gas_spilled)
-    evm.gas_left += from_gas_left
-    evm.state_gas_spilled -= from_gas_left
-    evm.state_gas_left += amount - from_gas_left
-
-
-def incorporate_child_on_success(evm: Evm, child_evm: Evm) -> None:
-    """
-    Incorporate the state of a successful `child_evm` into the parent `evm`.
+    Incorporate the state of a returning `child_evm` into the parent
+    `evm`.
+
+    Gas flows back to the parent regardless of the child's fate. A
+    failed child settles its own meter before returning -- its state
+    gas rolled back to the baseline, its [spill] refilled, and its
+    refunds discarded -- so absorbing the meter unconditionally
+    reclaims exactly the gas the child gives back. Everything else the
+    child accumulated -- logs, scheduled self-destructs, refunds, and
+    warmed access sets -- survives only on success, dying with a
+    failed child's reverted state.
 
     Parameters
     ----------
@@ -228,117 +205,34 @@ def incorporate_child_on_success(evm: Evm, child_evm: Evm) -> None:
     child_evm :
         The child evm to incorporate.
 
-    """
-    evm.gas_left += child_evm.gas_left
-    evm.state_gas_left += child_evm.state_gas_left
-    evm.state_gas_spilled += child_evm.state_gas_spilled
-    evm.logs += child_evm.logs
-    evm.refund_counter += child_evm.refund_counter
-    evm.accounts_to_delete.update(child_evm.accounts_to_delete)
-    evm.accessed_addresses.update(child_evm.accessed_addresses)
-    evm.accessed_storage_keys.update(child_evm.accessed_storage_keys)
-    evm.regular_gas_used += child_evm.regular_gas_used
-
-
-def refill_frame_state_gas(evm: Evm) -> None:
-    """
-    Roll back the frame's state gas in LIFO order on revert or halt.
-
-    The frame's state changes are undone, so the state gas it consumed
-    is credited back to `gas_left` first and then to the reservoir,
-    restoring the pools the charges drew from.
-
-    Parameters
-    ----------
-    evm :
-        The frame whose state gas is rolled back.
-
-    """
-    evm.gas_left += evm.state_gas_spilled
-    evm.state_gas_left = evm.message.state_gas_reservoir
-    evm.state_gas_spilled = Uint(0)
-
-
-def frame_state_gas_used(evm: Evm) -> int:
-    """
-    Return the net state gas consumed by a finished frame, including
-    any state gas committed as non-refillable earlier in the frame.
-
-    Equal to the reservoir drawn down ([`state_gas_reservoir`][sgr] at
-    the last commit -- or frame entry, absent one -- minus the
-    reservoir now) plus [`state_gas_spilled`][sgs] plus
-    [`committed_state_gas`][csg]. May be negative when refunds exceed
-    charges.
-
-    Parameters
-    ----------
-    evm :
-        The finished frame.
-
-    [sgr]: ref:ethereum.forks.amsterdam.vm.Message.state_gas_reservoir
-    [sgs]: ref:ethereum.forks.amsterdam.vm.Evm.state_gas_spilled
-    [csg]: ref:ethereum.forks.amsterdam.vm.Evm.committed_state_gas
-
-    """
-    return (
-        int(evm.message.state_gas_reservoir)
-        - int(evm.state_gas_left)
-        + int(evm.state_gas_spilled)
-        + evm.committed_state_gas
-    )
-
-
-def commit_frame_state_gas(evm: Evm) -> None:
-    """
-    Mark the state gas consumed so far as non-refillable and reset the
-    refill baseline.
-
-    The state this gas paid for (the delegations applied by
-    [`set_delegation`][sd]) outlives a later failure of the dispatched
-    code, so a subsequent [`refill_frame_state_gas`][refill] must not
-    credit it back. The consumption so far is folded into
-    [`committed_state_gas`][csg] and the reservoir baseline moves down
-    to the current level, so only charges made after this commit are
-    refillable.
-
-    Parameters
-    ----------
-    evm :
-        The frame whose state gas consumption is committed.
-
-    [sd]: ref:ethereum.forks.amsterdam.vm.eoa_delegation.set_delegation
-    [refill]: ref:ethereum.forks.amsterdam.vm.refill_frame_state_gas
-    [csg]: ref:ethereum.forks.amsterdam.vm.Evm.committed_state_gas
-
-    """
-    evm.committed_state_gas = frame_state_gas_used(evm)
-    evm.message.state_gas_reservoir = evm.state_gas_left
-    evm.state_gas_spilled = Uint(0)
-
-
-def incorporate_child_on_error(
-    evm: Evm,
-    child_evm: Evm,
-) -> None:
-    """
-    Incorporate the state of an unsuccessful `child_evm` into the parent `evm`.
-
-    The child rolls back its own state gas via `refill_frame_state_gas`
-    before returning (on both reverts and exceptional halts), so its
-    `gas_left` and reservoir already reflect the LIFO refill. The parent
-    therefore only reabsorbs the child's `gas_left` and reservoir.
-
-    Parameters
-    ----------
-    evm :
-        The parent `EVM`.
-    child_evm :
-        The child evm to incorporate.
+    [spill]: ref:ethereum.forks.amsterdam.vm.gas.GasMeter.state_gas_spilled
 
     """
-    evm.gas_left += child_evm.gas_left
-    evm.state_gas_left += child_evm.state_gas_left
-    evm.regular_gas_used += child_evm.regular_gas_used
+    child_meter = child_evm.gas_meter
+    # Only the top frame commits state gas; a child never carries any.
+    assert child_meter.state_gas_committed_spill == Uint(0)
+
+    if child_evm.error:
+        # A failed child arrives settled: rolled back to its baseline,
+        # spill refilled, refunds discarded.
+        assert child_meter.state_gas_spilled == Uint(0)
+        assert child_meter.refund_counter == 0
+        assert child_meter.state_gas_left == child_meter.state_gas_baseline
+
+    # Gas returns to the parent regardless of the child's fate.
+    # Note that upon failure, the child already arrives settled.
+    gas_meter = evm.gas_meter
+    gas_meter.gas_left += child_meter.gas_left
+    gas_meter.state_gas_left += child_meter.state_gas_left
+    gas_meter.state_gas_spilled += child_meter.state_gas_spilled
+    gas_meter.refund_counter += child_meter.refund_counter
+
+    # Everything else survives only on success.
+    if not child_evm.error:
+        evm.logs += child_evm.logs
+        evm.accounts_to_delete.update(child_evm.accounts_to_delete)
+        evm.accessed_addresses.update(child_evm.accessed_addresses)
+        evm.accessed_storage_keys.update(child_evm.accessed_storage_keys)
 
 
 def emit_transfer_log(