gas.py (in src/ethereum/forks/amsterdam/vm)

ethereum.forks.amsterdam.vm.gas

Ethereum Virtual Machine (EVM) Gas.

.. contents:: Table of Contents :backlinks: none :local:

Introduction

EVM gas constants and calculators.

StateGasCosts ¶

EIP-8037 state-gas constants.

Kept separate from GasCosts because these carry a different unit: state-byte counts that convert into gas via COST_PER_STATE_BYTE.

class StateGasCosts:

COST_PER_STATE_BYTE ¶

57	COST_PER_STATE_BYTE: Final[StateGasPerByte] = StateGasPerByte(Uint(1530))

STATE_BYTES_PER_NEW_ACCOUNT ¶

58	STATE_BYTES_PER_NEW_ACCOUNT: Final[Uint] = Uint(120)

STATE_BYTES_PER_STORAGE_SET ¶

59	STATE_BYTES_PER_STORAGE_SET: Final[Uint] = Uint(64)

STATE_BYTES_PER_AUTH_BASE ¶

60	STATE_BYTES_PER_AUTH_BASE: Final[Uint] = Uint(23)

STORAGE_SET ¶

61	STORAGE_SET: Final[StateGas] = (
62	STATE_BYTES_PER_STORAGE_SET * COST_PER_STATE_BYTE
63	)

NEW_ACCOUNT ¶

64	NEW_ACCOUNT: Final[StateGas] = (
65	STATE_BYTES_PER_NEW_ACCOUNT * COST_PER_STATE_BYTE
66	)

AUTH_BASE ¶

67	AUTH_BASE: Final[StateGas] = (
68	STATE_BYTES_PER_AUTH_BASE * COST_PER_STATE_BYTE
69	)

GasCosts ¶

Constant gas values for the EVM.

class GasCosts:

BASE ¶

79	BASE: Final[ExecutionGas] = ExecutionGas(Uint(2))

VERY_LOW ¶

80	VERY_LOW: Final[ExecutionGas] = ExecutionGas(Uint(3))

LOW ¶

81	LOW: Final[ExecutionGas] = ExecutionGas(Uint(5))

MID ¶

82	MID: Final[ExecutionGas] = ExecutionGas(Uint(8))

HIGH ¶

83	HIGH: Final[ExecutionGas] = ExecutionGas(Uint(10))

WARM_ACCESS ¶

86	WARM_ACCESS: Final[ExecutionGas] = ExecutionGas(Uint(100))

COLD_ACCOUNT_ACCESS ¶

87	COLD_ACCOUNT_ACCESS: Final[ExecutionGas] = ExecutionGas(Uint(3000))

COLD_STORAGE_ACCESS ¶

88	COLD_STORAGE_ACCESS: Final[ExecutionGas] = ExecutionGas(Uint(2100))

STORAGE_WRITE ¶

91	STORAGE_WRITE: Final[ExecutionGas] = ExecutionGas(Uint(10000))

CALL_VALUE ¶

95	CALL_VALUE: Final[ExecutionGas] = ExecutionGas(Uint(11300))

CALL_STIPEND ¶

96	CALL_STIPEND: Final[ExecutionGas] = ExecutionGas(Uint(2300))

ACCOUNT_WRITE ¶

97	ACCOUNT_WRITE: Final[ExecutionGas] = ExecutionGas(Uint(9000))

CODE_DEPOSIT_PER_BYTE ¶

100	CODE_DEPOSIT_PER_BYTE: Final[ExecutionGas] = ExecutionGas(Uint(200))

CODE_INIT_PER_WORD ¶

101	CODE_INIT_PER_WORD: Final[ExecutionGas] = ExecutionGas(Uint(2))

CREATE_ACCESS ¶

102	CREATE_ACCESS: Final[ExecutionGas] = ACCOUNT_WRITE + COLD_ACCOUNT_ACCESS

ZERO ¶

105	ZERO: Final[ExecutionGas] = ExecutionGas(Uint(0))

MEMORY_PER_WORD ¶

106	MEMORY_PER_WORD: Final[ExecutionGas] = ExecutionGas(Uint(3))

FAST_STEP ¶

107	FAST_STEP: Final[ExecutionGas] = ExecutionGas(Uint(5))

REFUND_STORAGE_CLEAR ¶

110	REFUND_STORAGE_CLEAR: Final[int] = int(
111	(STORAGE_WRITE + COLD_STORAGE_ACCESS) * Uint(4800) // Uint(5000)
112	)

PRECOMPILE_ECRECOVER ¶

115	PRECOMPILE_ECRECOVER: Final[ExecutionGas] = ExecutionGas(Uint(3000))

PRECOMPILE_P256VERIFY ¶

116	PRECOMPILE_P256VERIFY: Final[ExecutionGas] = ExecutionGas(Uint(6900))

PRECOMPILE_SHA256_BASE ¶

117	PRECOMPILE_SHA256_BASE: Final[ExecutionGas] = ExecutionGas(Uint(60))

PRECOMPILE_SHA256_PER_WORD ¶

118	PRECOMPILE_SHA256_PER_WORD: Final[ExecutionGas] = ExecutionGas(Uint(12))

PRECOMPILE_RIPEMD160_BASE ¶

119	PRECOMPILE_RIPEMD160_BASE: Final[ExecutionGas] = ExecutionGas(Uint(600))

PRECOMPILE_RIPEMD160_PER_WORD ¶

120	PRECOMPILE_RIPEMD160_PER_WORD: Final[ExecutionGas] = ExecutionGas(
121	Uint(120)
122	)

PRECOMPILE_IDENTITY_BASE ¶

123	PRECOMPILE_IDENTITY_BASE: Final[ExecutionGas] = ExecutionGas(Uint(15))

PRECOMPILE_IDENTITY_PER_WORD ¶

124	PRECOMPILE_IDENTITY_PER_WORD: Final[ExecutionGas] = ExecutionGas(Uint(3))

PRECOMPILE_BLAKE2F_PER_ROUND ¶

125	PRECOMPILE_BLAKE2F_PER_ROUND: Final[ExecutionGas] = ExecutionGas(Uint(1))

PRECOMPILE_POINT_EVALUATION ¶

126	PRECOMPILE_POINT_EVALUATION: Final[ExecutionGas] = ExecutionGas(
127	Uint(50000)
128	)

PRECOMPILE_BLS_G1ADD ¶

129	PRECOMPILE_BLS_G1ADD: Final[ExecutionGas] = ExecutionGas(Uint(375))

PRECOMPILE_BLS_G1MUL ¶

130	PRECOMPILE_BLS_G1MUL: Final[ExecutionGas] = ExecutionGas(Uint(12000))

PRECOMPILE_BLS_G1MAP ¶

131	PRECOMPILE_BLS_G1MAP: Final[ExecutionGas] = ExecutionGas(Uint(5500))

PRECOMPILE_BLS_G2ADD ¶

132	PRECOMPILE_BLS_G2ADD: Final[ExecutionGas] = ExecutionGas(Uint(600))

PRECOMPILE_BLS_G2MUL ¶

133	PRECOMPILE_BLS_G2MUL: Final[ExecutionGas] = ExecutionGas(Uint(22500))

PRECOMPILE_BLS_G2MAP ¶

134	PRECOMPILE_BLS_G2MAP: Final[ExecutionGas] = ExecutionGas(Uint(23800))

PRECOMPILE_ECADD ¶

135	PRECOMPILE_ECADD: Final[ExecutionGas] = ExecutionGas(Uint(150))

PRECOMPILE_ECMUL ¶

136	PRECOMPILE_ECMUL: Final[ExecutionGas] = ExecutionGas(Uint(6000))

PRECOMPILE_ECPAIRING_BASE ¶

137	PRECOMPILE_ECPAIRING_BASE: Final[ExecutionGas] = ExecutionGas(Uint(45000))

PRECOMPILE_ECPAIRING_PER_POINT ¶

138	PRECOMPILE_ECPAIRING_PER_POINT: Final[ExecutionGas] = ExecutionGas(
139	Uint(34000)
140	)

PER_BLOB ¶

143	PER_BLOB: Final[U64] = U64(2**17)

BLOB_SCHEDULE_TARGET ¶

144	BLOB_SCHEDULE_TARGET: Final[U64] = U64(14)

BLOB_TARGET_GAS_PER_BLOCK ¶

145	BLOB_TARGET_GAS_PER_BLOCK: Final[U64] = PER_BLOB * BLOB_SCHEDULE_TARGET

BLOB_BASE_COST ¶

146	BLOB_BASE_COST: Final[Uint] = Uint(2**13)

BLOB_SCHEDULE_MAX ¶

147	BLOB_SCHEDULE_MAX: Final[U64] = U64(21)

BLOB_MIN_GASPRICE ¶

148	BLOB_MIN_GASPRICE: Final[Uint] = Uint(1)

BLOB_BASE_FEE_UPDATE_FRACTION ¶

149	BLOB_BASE_FEE_UPDATE_FRACTION: Final[Uint] = Uint(11684671)

BLOCK_ACCESS_LIST_ITEM ¶

152	BLOCK_ACCESS_LIST_ITEM: Final[ExecutionGas] = ExecutionGas(Uint(2000))

TX_BASE ¶

155	TX_BASE: Final[ExecutionGas] = ExecutionGas(Uint(12000))

TX_CREATE ¶

156	TX_CREATE: Final[ExecutionGas] = ExecutionGas(Uint(32000))

TX_VALUE_COST ¶

157	TX_VALUE_COST: Final[ExecutionGas] = ExecutionGas(Uint(6000))

TX_DATA_TOKEN_STANDARD ¶

158	TX_DATA_TOKEN_STANDARD: Final[ExecutionGas] = ExecutionGas(Uint(4))

TX_DATA_TOKEN_FLOOR ¶

159	TX_DATA_TOKEN_FLOOR: Final[ExecutionGas] = ExecutionGas(Uint(16))

TX_ACCESS_LIST_ADDRESS ¶

160	TX_ACCESS_LIST_ADDRESS: Final[ExecutionGas] = (
161	COLD_ACCOUNT_ACCESS - WARM_ACCESS
162	)

TX_ACCESS_LIST_STORAGE_KEY ¶

163	TX_ACCESS_LIST_STORAGE_KEY: Final[ExecutionGas] = (
164	COLD_STORAGE_ACCESS - WARM_ACCESS
165	)

AUTH_TUPLE_BYTES ¶

168	AUTH_TUPLE_BYTES: Final[Uint] = Uint(101)

EXECUTION_PER_AUTH_BASE_COST ¶

169	EXECUTION_PER_AUTH_BASE_COST: Final[ExecutionGas] = ExecutionGas(
170	AUTH_TUPLE_BYTES * TX_DATA_TOKEN_FLOOR
171	+ PRECOMPILE_ECRECOVER
172	+ COLD_ACCOUNT_ACCESS
173	+ Uint(2) * WARM_ACCESS
174	)

LIMIT_ADJUSTMENT_FACTOR ¶

177	LIMIT_ADJUSTMENT_FACTOR: Final[Uint] = Uint(1024)

LIMIT_MINIMUM ¶

178	LIMIT_MINIMUM: Final[Uint] = Uint(5000)

OPCODE_ADD ¶

181	OPCODE_ADD: Final[ExecutionGas] = VERY_LOW

OPCODE_SUB ¶

182	OPCODE_SUB: Final[ExecutionGas] = VERY_LOW

OPCODE_MUL ¶

183	OPCODE_MUL: Final[ExecutionGas] = LOW

OPCODE_DIV ¶

184	OPCODE_DIV: Final[ExecutionGas] = LOW

OPCODE_SDIV ¶

185	OPCODE_SDIV: Final[ExecutionGas] = LOW

OPCODE_MOD ¶

186	OPCODE_MOD: Final[ExecutionGas] = LOW

OPCODE_SMOD ¶

187	OPCODE_SMOD: Final[ExecutionGas] = LOW

OPCODE_ADDMOD ¶

188	OPCODE_ADDMOD: Final[ExecutionGas] = MID

OPCODE_MULMOD ¶

189	OPCODE_MULMOD: Final[ExecutionGas] = MID

OPCODE_SIGNEXTEND ¶

190	OPCODE_SIGNEXTEND: Final[ExecutionGas] = LOW

OPCODE_LT ¶

191	OPCODE_LT: Final[ExecutionGas] = VERY_LOW

OPCODE_GT ¶

192	OPCODE_GT: Final[ExecutionGas] = VERY_LOW

OPCODE_SLT ¶

193	OPCODE_SLT: Final[ExecutionGas] = VERY_LOW

OPCODE_SGT ¶

194	OPCODE_SGT: Final[ExecutionGas] = VERY_LOW

OPCODE_EQ ¶

195	OPCODE_EQ: Final[ExecutionGas] = VERY_LOW

OPCODE_ISZERO ¶

196	OPCODE_ISZERO: Final[ExecutionGas] = VERY_LOW

OPCODE_AND ¶

197	OPCODE_AND: Final[ExecutionGas] = VERY_LOW

OPCODE_OR ¶

198	OPCODE_OR: Final[ExecutionGas] = VERY_LOW

OPCODE_XOR ¶

199	OPCODE_XOR: Final[ExecutionGas] = VERY_LOW

OPCODE_NOT ¶

200	OPCODE_NOT: Final[ExecutionGas] = VERY_LOW

OPCODE_BYTE ¶

201	OPCODE_BYTE: Final[ExecutionGas] = VERY_LOW

OPCODE_SHL ¶

202	OPCODE_SHL: Final[ExecutionGas] = VERY_LOW

OPCODE_SHR ¶

203	OPCODE_SHR: Final[ExecutionGas] = VERY_LOW

OPCODE_SAR ¶

204	OPCODE_SAR: Final[ExecutionGas] = VERY_LOW

OPCODE_CLZ ¶

205	OPCODE_CLZ: Final[ExecutionGas] = LOW

OPCODE_JUMP ¶

206	OPCODE_JUMP: Final[ExecutionGas] = MID

OPCODE_JUMPI ¶

207	OPCODE_JUMPI: Final[ExecutionGas] = HIGH

OPCODE_JUMPDEST ¶

208	OPCODE_JUMPDEST: Final[ExecutionGas] = ExecutionGas(Uint(1))

OPCODE_CALLDATALOAD ¶

209	OPCODE_CALLDATALOAD: Final[ExecutionGas] = VERY_LOW

OPCODE_BLOCKHASH ¶

210	OPCODE_BLOCKHASH: Final[ExecutionGas] = ExecutionGas(Uint(20))

OPCODE_COINBASE ¶

211	OPCODE_COINBASE: Final[ExecutionGas] = BASE

OPCODE_POP ¶

212	OPCODE_POP: Final[ExecutionGas] = BASE

OPCODE_MSIZE ¶

213	OPCODE_MSIZE: Final[ExecutionGas] = BASE

OPCODE_PC ¶

214	OPCODE_PC: Final[ExecutionGas] = BASE

OPCODE_GAS ¶

215	OPCODE_GAS: Final[ExecutionGas] = BASE

OPCODE_ADDRESS ¶

216	OPCODE_ADDRESS: Final[ExecutionGas] = BASE

OPCODE_ORIGIN ¶

217	OPCODE_ORIGIN: Final[ExecutionGas] = BASE

OPCODE_CALLER ¶

218	OPCODE_CALLER: Final[ExecutionGas] = BASE

OPCODE_CALLVALUE ¶

219	OPCODE_CALLVALUE: Final[ExecutionGas] = BASE

OPCODE_CALLDATASIZE ¶

220	OPCODE_CALLDATASIZE: Final[ExecutionGas] = BASE

OPCODE_CODESIZE ¶

221	OPCODE_CODESIZE: Final[ExecutionGas] = BASE

OPCODE_GASPRICE ¶

222	OPCODE_GASPRICE: Final[ExecutionGas] = BASE

OPCODE_TIMESTAMP ¶

223	OPCODE_TIMESTAMP: Final[ExecutionGas] = BASE

OPCODE_NUMBER ¶

224	OPCODE_NUMBER: Final[ExecutionGas] = BASE

OPCODE_GASLIMIT ¶

225	OPCODE_GASLIMIT: Final[ExecutionGas] = BASE

OPCODE_PREVRANDAO ¶

226	OPCODE_PREVRANDAO: Final[ExecutionGas] = BASE

OPCODE_RETURNDATASIZE ¶

227	OPCODE_RETURNDATASIZE: Final[ExecutionGas] = BASE

OPCODE_CHAINID ¶

228	OPCODE_CHAINID: Final[ExecutionGas] = BASE

OPCODE_BASEFEE ¶

229	OPCODE_BASEFEE: Final[ExecutionGas] = BASE

OPCODE_BLOBBASEFEE ¶

230	OPCODE_BLOBBASEFEE: Final[ExecutionGas] = BASE

OPCODE_SLOTNUM ¶

231	OPCODE_SLOTNUM: Final[ExecutionGas] = BASE

OPCODE_BLOBHASH ¶

232	OPCODE_BLOBHASH: Final[ExecutionGas] = ExecutionGas(Uint(3))

OPCODE_PUSH ¶

233	OPCODE_PUSH: Final[ExecutionGas] = VERY_LOW

OPCODE_PUSH0 ¶

234	OPCODE_PUSH0: Final[ExecutionGas] = BASE

OPCODE_DUP ¶

235	OPCODE_DUP: Final[ExecutionGas] = VERY_LOW

OPCODE_SWAP ¶

236	OPCODE_SWAP: Final[ExecutionGas] = VERY_LOW

OPCODE_DUPN ¶

237	OPCODE_DUPN: Final[ExecutionGas] = VERY_LOW

OPCODE_SWAPN ¶

238	OPCODE_SWAPN: Final[ExecutionGas] = VERY_LOW

OPCODE_EXCHANGE ¶

239	OPCODE_EXCHANGE: Final[ExecutionGas] = VERY_LOW

OPCODE_TLOAD ¶

240	OPCODE_TLOAD: Final[ExecutionGas] = ExecutionGas(Uint(100))

OPCODE_TSTORE ¶

241	OPCODE_TSTORE: Final[ExecutionGas] = ExecutionGas(Uint(100))

OPCODE_RETURNDATACOPY_BASE ¶

244	OPCODE_RETURNDATACOPY_BASE: Final[ExecutionGas] = VERY_LOW

OPCODE_RETURNDATACOPY_PER_WORD ¶

245	OPCODE_RETURNDATACOPY_PER_WORD: Final[ExecutionGas] = ExecutionGas(Uint(3))

OPCODE_CALLDATACOPY_BASE ¶

246	OPCODE_CALLDATACOPY_BASE: Final[ExecutionGas] = VERY_LOW

OPCODE_CODECOPY_BASE ¶

247	OPCODE_CODECOPY_BASE: Final[ExecutionGas] = VERY_LOW

OPCODE_MCOPY_BASE ¶

248	OPCODE_MCOPY_BASE: Final[ExecutionGas] = VERY_LOW

OPCODE_MLOAD_BASE ¶

249	OPCODE_MLOAD_BASE: Final[ExecutionGas] = VERY_LOW

OPCODE_MSTORE_BASE ¶

250	OPCODE_MSTORE_BASE: Final[ExecutionGas] = VERY_LOW

OPCODE_MSTORE8_BASE ¶

251	OPCODE_MSTORE8_BASE: Final[ExecutionGas] = VERY_LOW

OPCODE_COPY_PER_WORD ¶

252	OPCODE_COPY_PER_WORD: Final[ExecutionGas] = ExecutionGas(Uint(3))

OPCODE_EXP_BASE ¶

253	OPCODE_EXP_BASE: Final[ExecutionGas] = ExecutionGas(Uint(10))

OPCODE_EXP_PER_BYTE ¶

254	OPCODE_EXP_PER_BYTE: Final[ExecutionGas] = ExecutionGas(Uint(50))

OPCODE_KECCAK256_BASE ¶

255	OPCODE_KECCAK256_BASE: Final[ExecutionGas] = ExecutionGas(Uint(30))

OPCODE_KECCAK256_PER_WORD ¶

256	OPCODE_KECCAK256_PER_WORD: Final[ExecutionGas] = ExecutionGas(Uint(6))

OPCODE_LOG_BASE ¶

257	OPCODE_LOG_BASE: Final[ExecutionGas] = ExecutionGas(Uint(375))

OPCODE_LOG_DATA_PER_BYTE ¶

258	OPCODE_LOG_DATA_PER_BYTE: Final[ExecutionGas] = ExecutionGas(Uint(8))

OPCODE_LOG_TOPIC ¶

259	OPCODE_LOG_TOPIC: Final[ExecutionGas] = ExecutionGas(Uint(375))

OPCODE_SELFDESTRUCT_BASE ¶

260	OPCODE_SELFDESTRUCT_BASE: Final[ExecutionGas] = ExecutionGas(Uint(5000))

MAX_BLOB_GAS_PER_BLOCK ¶

263	MAX_BLOB_GAS_PER_BLOCK: Final[U64] = (
264	GasCosts.BLOB_SCHEDULE_MAX * GasCosts.PER_BLOB
265	)

GasMeter ¶

Track a frame's gas consumption across both gas dimensions.

Bundle every mutable gas quantity a frame maintains, so the frame and its settlement work against one object instead of a scatter of fields on the Evm.

268	@final

269	@dataclass

class GasMeter:

gas_left ¶

Gas still available from the frame's execution-gas grant. Pays execution-gas charges, and state charges as spill once the reservoir empties.

281	gas_left: ExecutionGas

state_gas_left ¶

State gas still available in the frame's reservoir. Charges draw from here first and spill into gas_left once it is empty.

290	state_gas_left: StateGas

state_gas_baseline ¶

Reservoir level a rollback refills to: the frame's grant at entry, moved down by commit_state_gas when charges become non-refillable.

296	state_gas_baseline: StateGas

refund_counter ¶

Gas eligible for refund at the end of the transaction.

305	refund_counter: int = 0

Execution gas spent covering state charges after the reservoir emptied. Credited back to gas_left first, in LIFO order, on a refund or failure. EIP-8037 names this quantity state_gas_from_gas_left.

308	state_gas_spilled: StateGas = StateGas(Uint(0))

state_gas_committed_spill ¶

Spill that commit_state_gas marked non-refillable. It outlives the rollbacks restore_state_gas performs; only restore_state_gas_to_entry credits it back to gas_left. Committed reservoir draw needs no counter of its own: each commit lowers the baseline, so it is the frame's grant minus state_gas_baseline.

318	state_gas_committed_spill: StateGas = StateGas(Uint(0))

ExtendMemory ¶

Define the parameters for memory extension in opcodes.

cost: ExecutionGas The gas required to perform the extension expand_by: ethereum.base_types.Uint The size by which the memory will be extended

334	@final

335	@dataclass

class ExtendMemory:

cost ¶

346	cost: ExecutionGas

expand_by ¶

347	expand_by: Uint

MessageCallGas ¶

Define the gas cost and gas given to the sub-call for executing the call opcodes.

cost: ExecutionGas The gas required to execute the call opcode, excludes memory expansion costs. sub_call: ExecutionGas The portion of gas available to sub-calls that is refundable if not consumed.

350	@final

351	@dataclass

class MessageCallGas:

cost ¶

365	cost: ExecutionGas

sub_call ¶

366	sub_call: ExecutionGas

check_gas ¶

Checks if amount gas is available without charging it. Raises OutOfGasError if insufficient gas.

Parameters

evm : The current EVM. amount : The amount of execution gas to check.

def check_gas(evm: "Evm", amount: ExecutionGas) -> None:

370	<snip>
382	if evm.gas_meter.gas_left < amount:
383	raise OutOfGasError

charge_gas_from_meter ¶

Subtracts amount from gas_left (execution gas).

Parameters

gas_meter : The gas meter. amount : The amount of execution gas the current operation requires.

def charge_gas_from_meter(gas_meter: GasMeter, amount: ExecutionGas) -> None:

387	<snip>
398	if gas_meter.gas_left < amount:
399	raise OutOfGasError
400	gas_meter.gas_left -= amount

charge_gas ¶

Subtracts amount from gas_left (execution gas).

Parameters

evm : The current EVM. amount : The amount of execution gas the current operation requires.

def charge_gas(evm: "Evm", amount: ExecutionGas) -> None:

404	<snip>
415	evm_trace(evm, GasAndRefund(int(amount)))
416
417	charge_gas_from_meter(evm.gas_meter, amount)

charge_state_gas_from_meter ¶

Subtracts amount from the state gas reservoir, then from gas_left when the reservoir is empty, tracking any spill.

Parameters

gas_meter : The gas meter. amount : The amount of state gas the current operation requires.

def charge_state_gas_from_meter(gas_meter: GasMeter, amount: StateGas) -> None:

421	<snip>
435	if gas_meter.state_gas_left >= amount:
436	gas_meter.state_gas_left -= amount
437	elif Uint(gas_meter.state_gas_left) + Uint(gas_meter.gas_left) >= amount:
438	remainder = amount - gas_meter.state_gas_left
439	gas_meter.state_gas_left = StateGas(Uint(0))
440	gas_meter.gas_left = ExecutionGas(gas_meter.gas_left - Uint(remainder))
441	gas_meter.state_gas_spilled += remainder
442	else:
443	raise OutOfGasError

charge_state_gas ¶

Subtracts amount from the state gas reservoir, then from gas_left when the reservoir is empty, tracking any spill.

Parameters

evm : The current EVM. amount : The amount of state gas the current operation requires.

def charge_state_gas(evm: "Evm", amount: StateGas) -> None:

447	<snip>
461	evm_trace(evm, StateGasAndRefund(int(amount)))
462
463	charge_state_gas_from_meter(evm.gas_meter, amount)

commit_state_gas ¶

Mark the state gas spent so far as non-refillable.

A later rollback via restore_state_gas leaves the state bought so far in place, so it must not credit this gas back. In the top frame that protects the delegations applied by set_delegation, which survive a failure of the dispatched code. A failure that reverts the committed state as well -- one raised before dispatch -- must instead undo the commit with restore_state_gas_to_entry.

Move the baseline down to the current reservoir level and fold the spill into state_gas_committed_spill, so later refunds route to the reservoir instead of back into gas_left.

Parameters

gas_meter : The frame's gas meter.

def commit_state_gas(gas_meter: GasMeter) -> None:

467	<snip>
492	# Only charges precede a commit, so no refund has pushed the
493	# reservoir above the baseline: a commit only ever lowers it.
494	assert gas_meter.state_gas_left <= gas_meter.state_gas_baseline
495	gas_meter.state_gas_committed_spill += gas_meter.state_gas_spilled
496	gas_meter.state_gas_baseline = gas_meter.state_gas_left
497	gas_meter.state_gas_spilled = StateGas(Uint(0))

restore_state_gas ¶

Roll the frame's state gas back to the baseline on revert or halt.

The frame's state changes are undone, so the state gas consumed since the baseline is credited back in LIFO order: the spill returns to gas_left first, then the reservoir resets to the baseline. The refunds accrued on the undone changes are discarded with them. State gas committed as non-refillable stays charged.

Parameters

gas_meter : The frame's gas meter.

def restore_state_gas(gas_meter: GasMeter) -> None:

501	<snip> # noqa: E501
519	gas_meter.gas_left = ExecutionGas(
520	gas_meter.gas_left + Uint(gas_meter.state_gas_spilled)
521	)
522	gas_meter.state_gas_spilled = StateGas(Uint(0))
523	gas_meter.state_gas_left = gas_meter.state_gas_baseline
524	gas_meter.refund_counter = 0

restore_state_gas_to_entry ¶

Roll the frame's state gas back to frame entry, undoing any commit.

Used when the transaction-state rollback also reverts the applied delegations a commit_state_gas protected: every state charge refills -- all spill, committed or not, returns to gas_left -- and the baseline resets to the frame's grant.

Parameters

gas_meter : The frame's gas meter. state_gas_reservoir : The frame's immutable state gas grant.

def restore_state_gas_to_entry(gas_meter: GasMeter, state_gas_reservoir: StateGas) -> None:

530	<snip> # noqa: E501
549	# The baseline starts at the grant and only ever moves down.
550	assert gas_meter.state_gas_baseline <= state_gas_reservoir
551	# Only pre-dispatch failures roll back to entry, and no refund
552	# accrues before dispatch.
553	assert gas_meter.refund_counter == 0
554	gas_meter.gas_left = ExecutionGas(
555	gas_meter.gas_left
556	+ Uint(gas_meter.state_gas_spilled)
557	+ Uint(gas_meter.state_gas_committed_spill)
558	)
559	gas_meter.state_gas_spilled = StateGas(Uint(0))
560	gas_meter.state_gas_committed_spill = StateGas(Uint(0))
561	gas_meter.state_gas_left = state_gas_reservoir
562	gas_meter.state_gas_baseline = state_gas_reservoir

tx_state_gas_used ¶

Return the net state gas a transaction's execution consumed.

Measured off the top frame's finished gas meter: the reservoir drawn down since the transaction's grant plus the spill, outstanding or committed. May be negative when refunds exceed charges.

Parameters

gas_meter : The top frame's finished gas meter. state_gas_reservoir : The transaction's immutable state gas grant.

Returns

state_gas_used : int The net state gas consumed.

def tx_state_gas_used(gas_meter: GasMeter, state_gas_reservoir: StateGas) -> int:

568	<snip>
591	# The baseline starts at the grant and only ever moves down.
592	assert gas_meter.state_gas_baseline <= state_gas_reservoir
593	return (
594	int(state_gas_reservoir)
595	- int(gas_meter.state_gas_left)
596	+ int(gas_meter.state_gas_spilled)
597	+ int(gas_meter.state_gas_committed_spill)
598	)

credit_state_gas_refund ¶

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 refunds credit the pool charged last first: gas_left up to the spill, then the reservoir. This restores the exact pools the charge drew from, so the two never drift.

Parameters

gas_meter : The gas meter crediting the refund. amount : The refund amount to credit.

def credit_state_gas_refund(gas_meter: GasMeter, amount: StateGas) -> None:

602	<snip>
620	from_gas_left = min(amount, gas_meter.state_gas_spilled)
621	gas_meter.gas_left = ExecutionGas(gas_meter.gas_left + Uint(from_gas_left))
622	gas_meter.state_gas_spilled -= from_gas_left
623	gas_meter.state_gas_left += amount - from_gas_left

forfeit_remaining_gas ¶

Consume all remaining execution gas on an exceptional halt.

Parameters

gas_meter : The halted frame's gas meter.

def forfeit_remaining_gas(gas_meter: GasMeter) -> None:

627	<snip>
636	# A rollback owes any outstanding spill back to `gas_left`; it
637	# must be restored before the remainder burns.
638	assert gas_meter.state_gas_spilled == Uint(0)
639	gas_meter.gas_left = ExecutionGas(Uint(0))

withhold_create_gas ¶

Withhold and return the gas made available to a CREATE* child.

Deduct the all-but-one-64th share from the frame's gas_left and return it as the child frame's execution-gas grant.

Parameters

gas_meter : The creating frame's gas meter.

Returns

child_gas : ExecutionGas The execution gas granted to the child frame.

def withhold_create_gas(gas_meter: GasMeter) -> ExecutionGas:

643	<snip>
660	child_gas = max_message_call_gas(gas_meter.gas_left)
661	gas_meter.gas_left -= child_gas
662	return child_gas

drain_state_gas_reservoir ¶

Empty the frame's state gas reservoir for a child frame.

A child frame receives the parent's entire reservoir; there is no all-but-one-64th rule for state gas. The parent's reservoir is restored when the child returns.

Parameters

gas_meter : The parent frame's gas meter.

Returns

reservoir : StateGas The state gas granted to the child frame.

def drain_state_gas_reservoir(gas_meter: GasMeter) -> StateGas:

666	<snip>
684	reservoir = gas_meter.state_gas_left
685	gas_meter.state_gas_left = StateGas(Uint(0))
686	return reservoir

restore_child_gas ¶

Return a child frame's unused gas grant to the parent.

Used when the child frame is never entered (for example, a stack depth or balance check fails): the withheld execution gas and drained reservoir are returned untouched.

Parameters

gas_meter : The parent frame's gas meter. gas : The execution gas grant to return. state_gas_reservoir : The state gas reservoir to return.

def restore_child_gas(gas_meter: GasMeter, gas: ExecutionGas, state_gas_reservoir: StateGas) -> None:

692	<snip>
709	gas_meter.gas_left += gas
710	gas_meter.state_gas_left += state_gas_reservoir

calculate_memory_gas_cost ¶

Calculates the gas cost for allocating memory to the smallest multiple of 32 bytes, such that the allocated size is at least as big as the given size.

Parameters

size_in_bytes : The size of the data in bytes.

Returns

total_gas_cost : ExecutionGas The gas cost for storing data in memory.

def calculate_memory_gas_cost(size_in_bytes: Uint) -> ExecutionGas:

714	<snip>
730	size_in_words = ceil32(size_in_bytes) // Uint(32)
731	linear_cost = size_in_words * GasCosts.MEMORY_PER_WORD
732	quadratic_cost = size_in_words ** Uint(2) // Uint(512)
733	total_gas_cost = linear_cost + quadratic_cost
734	try:
735	return ExecutionGas(total_gas_cost)
736	except ValueError as e:
737	raise OutOfGasError from e

calculate_gas_extend_memory ¶

Calculates the gas amount to extend memory.

Parameters

memory : Memory contents of the EVM. extensions: List of extensions to be made to the memory. Consists of a tuple of start position and size.

Returns

extend_memory: ExtendMemory

def calculate_gas_extend_memory(memory: bytearray, extensions: List[Tuple[U256, U256]]) -> ExtendMemory:

743	<snip>
759	size_to_extend = Uint(0)
760	to_be_paid = GasCosts.ZERO
761	current_size = ulen(memory)
762	for start_position, size in extensions:
763	if size == 0:
764	continue
765	before_size = ceil32(current_size)
766	after_size = ceil32(Uint(start_position) + Uint(size))
767	if after_size <= before_size:
768	continue
769
770	size_to_extend += after_size - before_size
771	already_paid = calculate_memory_gas_cost(before_size)
772	total_cost = calculate_memory_gas_cost(after_size)
773	to_be_paid += total_cost - already_paid
774
775	current_size = after_size
776
777	return ExtendMemory(to_be_paid, size_to_extend)

calculate_message_call_gas ¶

Calculates the MessageCallGas (cost and gas made available to the sub-call) for executing call Opcodes.

Parameters

value: The amount of ETH that needs to be transferred. gas : The amount of gas provided to the message-call. gas_left : The amount of gas left in the current frame. memory_cost : The amount needed to extend the memory in the current frame. extra_gas : The amount of gas needed for transferring value + creating a new account inside a message call. call_stipend : The amount of stipend provided to a message call to execute code while transferring value (ETH).

Returns

message_call_gas: MessageCallGas

def calculate_message_call_gas(value: U256, gas: ExecutionGas, gas_left: ExecutionGas, memory_cost: ExecutionGas, extra_gas: ExecutionGas, call_stipend: ExecutionGas) -> MessageCallGas:

788	<snip>
814	call_stipend = GasCosts.ZERO if value == 0 else call_stipend
815	if gas_left < extra_gas + memory_cost:
816	return MessageCallGas(gas + extra_gas, gas + call_stipend)
817
818	gas = min(gas, max_message_call_gas(gas_left - memory_cost - extra_gas))
819
820	return MessageCallGas(gas + extra_gas, gas + call_stipend)

max_message_call_gas ¶

Calculates the maximum gas that is allowed for making a message call.

Parameters

gas : The amount of gas provided to the message-call.

Returns

max_allowed_message_call_gas: ExecutionGas The maximum gas allowed for making the message-call.

def max_message_call_gas(gas: ExecutionGas) -> ExecutionGas:

824	<snip>
838	return ExecutionGas(gas - (gas // Uint(64)))

init_code_cost ¶

Calculates the gas to be charged for the init code in CREATE* opcodes as well as create transactions.

Parameters

init_code_length : The length of the init code provided to the opcode or a create transaction

Returns

init_code_gas: ExecutionGas The gas to be charged for the init code.

def init_code_cost(init_code_length: Uint) -> ExecutionGas:

842	<snip>
858	return ExecutionGas(
859	GasCosts.CODE_INIT_PER_WORD * ceil32(init_code_length) // Uint(32)
860	)

calculate_excess_blob_gas ¶

Calculates the excess blob gas for the current block based on the gas used in the parent block.

Parameters

parent_header : The parent block of the current block.

Returns

excess_blob_gas: ethereum.base_types.U64 The excess blob gas for the current block.

def calculate_excess_blob_gas(parent_header: Header | PreviousHeader) -> U64:

866	<snip>
881	# Defaults for a parent without blob gas fields.
882	excess_blob_gas = U64(0)
883	blob_gas_used = U64(0)
884	base_fee_per_gas = Uint(0)
885
886	if isinstance(parent_header, (Header, PreviousHeader)):
887	# Read them from any parent that carries the fields, so
888	# accumulated excess blob gas survives a fork transition.
889	excess_blob_gas = parent_header.excess_blob_gas
890	blob_gas_used = parent_header.blob_gas_used
891	base_fee_per_gas = parent_header.base_fee_per_gas
892
893	parent_blob_gas = excess_blob_gas + blob_gas_used
894	if parent_blob_gas < GasCosts.BLOB_TARGET_GAS_PER_BLOCK:
895	return U64(0)
896
897	target_blob_gas_price = Uint(GasCosts.PER_BLOB)
898	target_blob_gas_price *= calculate_blob_gas_price(excess_blob_gas)
899
900	base_blob_tx_price = GasCosts.BLOB_BASE_COST * base_fee_per_gas
901	if base_blob_tx_price > target_blob_gas_price:
902	blob_schedule_delta = (
903	GasCosts.BLOB_SCHEDULE_MAX - GasCosts.BLOB_SCHEDULE_TARGET
904	)
905	return (
906	excess_blob_gas
907	+ blob_gas_used * blob_schedule_delta // GasCosts.BLOB_SCHEDULE_MAX
908	)
909
910	return parent_blob_gas - GasCosts.BLOB_TARGET_GAS_PER_BLOCK

calculate_total_blob_gas ¶

Calculate the total blob gas for a transaction.

Parameters

tx : The transaction for which the blob gas is to be calculated.

Returns

total_blob_gas: ethereum.base_types.Uint The total blob gas for the transaction.

def calculate_total_blob_gas(tx: Transaction) -> U64:

914	<snip>
928	if isinstance(tx, BlobTransaction):
929	return GasCosts.PER_BLOB * U64(len(tx.blob_versioned_hashes))
930	else:
931	return U64(0)

calculate_blob_gas_price ¶

Calculate the blob gasprice for a block.

Parameters

excess_blob_gas : The excess blob gas for the block.

Returns

blob_gasprice: Uint The blob gasprice.

def calculate_blob_gas_price(excess_blob_gas: U64) -> Uint:

935	<snip>
949	return taylor_exponential(
950	GasCosts.BLOB_MIN_GASPRICE,
951	Uint(excess_blob_gas),
952	GasCosts.BLOB_BASE_FEE_UPDATE_FRACTION,
953	)

calculate_data_fee ¶

Calculate the blob data fee for a transaction.

Parameters

excess_blob_gas : The excess_blob_gas for the execution. tx : The transaction for which the blob data fee is to be calculated.

Returns

data_fee: Uint The blob data fee.

def calculate_data_fee(excess_blob_gas: U64, tx: Transaction) -> Uint:

957	<snip>
973	return Uint(calculate_total_blob_gas(tx)) * calculate_blob_gas_price(
974	excess_blob_gas
975	)

check_max_fee_per_blob_gas ¶

Check that a transaction carrying blobs pays at least the blob gas price.

A transaction without blobs pays no blob fee, so its fee cap is not checked.

Parameters

blob_versioned_hashes : The transaction's blob versioned hashes. max_fee_per_blob_gas : The transaction's fee cap per unit of blob gas. excess_blob_gas : The block's excess blob gas.

Raises

InsufficientMaxFeePerBlobGasError : If the fee cap does not cover the blob gas price.

def check_max_fee_per_blob_gas(blob_versioned_hashes: Tuple[VersionedHash, ...], max_fee_per_blob_gas: U256, excess_blob_gas: U64) -> None:

983	<snip>
1005	if not blob_versioned_hashes:
1006	return
1007
1008	blob_gas_price = calculate_blob_gas_price(excess_blob_gas)
1009	if Uint(max_fee_per_blob_gas) < blob_gas_price:
1010	raise InsufficientMaxFeePerBlobGasError(
1011	"insufficient max fee per blob gas"
1012	)

check_block_gas_capacity ¶

Check that the transaction fits the block's remaining gas capacity.

Each dimension is checked against its own remaining budget: execution gas, where a single transaction can consume at most TX_MAX_GAS_LIMIT; state gas; and blob gas.

Parameters

block_env : The block scoped environment. block_output : The block output for the current block. tx_gas : The transaction's gas limit. tx_blob_gas : The blob gas used by the transaction.

Raises

GasUsedExceedsLimitError : If the transaction exceeds the block's remaining execution or state gas. BlobGasLimitExceededError : If the transaction exceeds the block's remaining blob gas.

def check_block_gas_capacity(block_env: "BlockEnvironment", block_output: "BlockOutput", tx_gas: Uint, tx_blob_gas: U64) -> None:

1021	<snip> # noqa: E501
1050	execution_gas_available = (
1051	block_env.block_gas_limit - block_output.block_gas_used
1052	)
1053	state_gas_available = (
1054	block_env.block_gas_limit - block_output.block_state_gas_used
1055	)
1056	blob_gas_available = MAX_BLOB_GAS_PER_BLOCK - block_output.blob_gas_used
1057
1058	if min(TX_MAX_GAS_LIMIT, tx_gas) > execution_gas_available:
1059	raise GasUsedExceedsLimitError("execution gas used exceeds limit")
1060
1061	if tx_gas > state_gas_available:
1062	raise GasUsedExceedsLimitError("state gas used exceeds limit")
1063
1064	if tx_blob_gas > blob_gas_available:
1065	raise BlobGasLimitExceededError("blob gas limit exceeded")

EvmGasAllocation ¶

Split of a transaction's EVM gas across the two dimensions.

1068	@final

1069	@dataclass

class EvmGasAllocation:

execution_gas ¶

Execution gas granted to the top frame, capped by the budget.

1075	execution_gas: ExecutionGas

state_gas_reservoir ¶

State gas set aside for the top frame's reservoir.

1078	state_gas_reservoir: StateGas

allocate_evm_gas ¶

Split EVM gas into an execution-gas grant and a state reservoir.

After the intrinsic cost is removed, the remaining EVM gas is divided into execution gas -- capped by the execution-gas budget that remains below TX_MAX_GAS_LIMIT -- and a state gas reservoir that holds whatever exceeds that cap.

Only valid once validate_transaction has confirmed the transaction can afford its intrinsic cost, which guarantees the subtractions below do not underflow.

Parameters

tx_gas : The transaction's gas limit. intrinsic : The transaction's intrinsic gas cost.

Returns

allocation : EvmGasAllocation The execution gas grant and state gas reservoir.

def allocate_evm_gas(tx_gas: Uint, intrinsic: IntrinsicGasCost) -> EvmGasAllocation:

1085	<snip>
1110	evm_gas = tx_gas - Uint(intrinsic.execution)
1111	execution_gas_budget = TX_MAX_GAS_LIMIT - intrinsic.execution
1112	execution_gas = ExecutionGas(min(execution_gas_budget, evm_gas))
1113	state_gas_reservoir = StateGas(evm_gas - execution_gas)
1114	return EvmGasAllocation(execution_gas, state_gas_reservoir)

TransactionGasSettlement ¶

Settled gas amounts for a finished transaction.

Hold only gas figures; the caller turns them into fee payments and block-accounting updates.

1117	@final

1118	@dataclass

class TransactionGasSettlement:

gas_used ¶

Total gas charged to the sender, after refund and floor.

1127	gas_used: Uint

gas_left ¶

Gas returned to the sender, priced at the effective gas price.

1130	gas_left: Uint

execution_gas_used ¶

Execution gas the transaction contributes to the block total.

1133	execution_gas_used: ExecutionGas

state_gas_used ¶

State gas the transaction contributes to the block total.

1136	state_gas_used: StateGas

settle_transaction_gas ¶

Settle a transaction's gas after execution.

Compute, in order:

the gas used before refunds, from the gas limit less the execution gas and reservoir the top frame returned;
the refund, capped at one fifth of that pre-refund usage;
the gas used, taken as the larger of the post-refund usage and the calldata floor, so a transaction never pays below the floor; and
the per-dimension block amounts: the state gas used (clamped to zero, since refunds can drive it negative) and the execution gas used, which carries the floor because the floor binds the execution dimension. Unlike the sender-facing gas_used, it ignores refunds: block accounting counts pre-refund gas (EIP-7778).

Parameters

tx_gas : The transaction's gas limit. calldata_floor : The transaction's calldata floor gas. gas_left : Execution gas the top frame returned. state_gas_left : State gas reservoir the top frame returned. refund_counter : The refund the top frame accrued. state_gas_used : Net state gas the top frame consumed, possibly negative.

Returns

settlement : TransactionGasSettlement The settled gas amounts.

def settle_transaction_gas(tx_gas: Uint, calldata_floor: Uint, gas_left: ExecutionGas, state_gas_left: StateGas, refund_counter: U256, state_gas_used: int) -> TransactionGasSettlement:

1148	<snip>
1188	gas_used_before_refund = tx_gas - gas_left - state_gas_left
1189	gas_refund = min(gas_used_before_refund // Uint(5), Uint(refund_counter))
1190	gas_used_after_refund = gas_used_before_refund - gas_refund
1191	gas_used = max(gas_used_after_refund, calldata_floor)
1192
1193	settled_state_gas_used = StateGas(Uint(max(0, state_gas_used)))
1194	execution_gas_used = ExecutionGas(
1195	max(
1196	gas_used_before_refund - settled_state_gas_used,
1197	calldata_floor,
1198	)
1199	)
1200	return TransactionGasSettlement(
1201	gas_used=gas_used,
1202	gas_left=tx_gas - gas_used,
1203	execution_gas_used=execution_gas_used,
1204	state_gas_used=settled_state_gas_used,
1205	)

Search Results

ethereum.forks.amsterdam.vm.gas

Introduction