Skip to content

Test SSTORE Refunds

Documentation for tests/amsterdam/eip8038_state_access_gas_cost_increase/test_sstore_refunds.py@ffe48572.

Generate fixtures for these test cases for Bogota with:

fill -v tests/amsterdam/eip8038_state_access_gas_cost_increase/test_sstore_refunds.py --fork Bogota

Tests for EIP-8038: State-access gas cost update.

The headline mechanism of the spec is the SSTORE clear-refund reversal: refund_counter is decremented by REFUND_STORAGE_CLEAR when a slot's original value is non-zero, its current value is zero and the new value is non-zero (a slot cleared earlier in the same transaction is set to a non-zero value again). The spec reverses the clear refund "so that clearing and then restoring a slot within the same transaction is never net-profitable". The reversal fires on any non-zero rewrite: test_sstore_clear_then_reset_nets_zero covers the x -> 0 -> y path and test_sstore_clear_then_restore_original the x -> 0 -> x round trip, where the reversal coincides with the STORAGE_WRITE refund.

This module covers the EIP-8038 execution SSTORE refund schedule via the transaction receipt's cumulative_gas_used:

  • Clearing a slot whose original value is non-zero grants REFUND_STORAGE_CLEAR to refund_counter (no EIP-8037 state refund, since no state was created).
  • Clearing then re-setting the same non-zero-original slot nets a zero refund: the clear grant is reversed (refund -= REFUND_STORAGE_CLEAR) exactly when original != 0 and current == 0 and a non-zero value is written back.
  • Restoring a non-zero-original slot to its original value refunds the write cost STORAGE_WRITE.
  • The applied refund is capped at gas_used // 5 (EIP-3529 quotient).

All refunds use a non-zero original so the state-creation refund owned by EIP-8037 is never involved; only the EIP-8038 execution dimension is exercised.

Test Functions Overview

Name Type Cases (Bogota) Description
test_sstore_clear_grants_refund state_test 1 Clearing a non-zero-original slot grants REFUND_STORAGE_CLEAR.
test_sstore_clear_refund_granted_twice state_test 1 The clear refund is granted on each clear of a non-zero slot, not
test_sstore_clear_then_reset_nets_zero state_test 1 Clearing then re-setting a non-zero-original slot nets zero refund.
test_sstore_clear_then_restore_original state_test 1 Clearing then restoring a slot's original value nets one write refund.
test_sstore_clear_then_rewrite_zero_grants_refund_once state_test 1 Rewriting zero over an already-cleared slot grants no second refund.
test_sstore_refund_cap_exact_equality state_test 1 The applied refund equals the EIP-3529 cap at exact equality.
test_sstore_refund_quotient_cap state_test 3 The applied refund saturates at the EIP-3529 quotient cap.
test_sstore_restore_nonzero_refunds_write state_test 1 Restoring a non-zero-original slot refunds the write cost.
test_sstore_write_charged_each_move_away state_test 1 STORAGE_WRITE is charged by each write that moves the slot away