Improve MessageCallGas documentation

[trocher]

What was wrong?

• MessageCallGas.cost's documentation stated that it was "The non-refundable portion of gas reserved for executing the call opcode.". However, MessageCallGas.cost includes the gas to be passed to the sub-call (excluding the 2300 gas stipend) and hence, it is not true that it is non-refundable since some of the gas passed might be refunded upon returning from the sub-call.

• The name MessageCallGas.stipend can be misleading as "stipend" is also often used to refer to the 2300 gas stipend appended to calls with a non-null value.

How was it fixed?

• Updated the documentation of MessageCallGas.cost to remove the "non-refundable" mention.
• Renamed MessageCallGas.stipend to MessageCallGas.sub_call.

Cute Animal Picture

[SamWilsn]

Your analysis seems sound; cost must contain the total cost of the instruction. See:

execution-specs/src/ethereum/arrow_glacier/vm/instructions/system.py

Line 354 in 32992ad

charge_gas(evm, message_call_gas.cost + extend_memory.cost)

[SamWilsn]

Would it make sense to also rename cost to total or something similar? Looks like it excludes the memory expansion cost though, and that might be a tad misleading.

[trocher]

• Added in a comment that it excludes memory expansion to be explicit.
• Keeping cost in the variable name is good imo since it is added to some other cost afterwards, maybe total_cost would work?

execution-specs/src/ethereum/arrow_glacier/vm/instructions/system.py

Line 353 in 6c337f7

charge_gas(evm, message_call_gas.cost + extend_memory.cost)