EIP-7877 Extension of the RETURN instruction (Enhanced RETURN opcodes)
No call decision · EVM & execution · EIP status Stagnant · created 2025-01-31
Adds three new instructions that return directly from storage, transient storage, and the return data buffer, in place of the RETURN instruction, which could previously only return data from memory, and renames the existing RETURN to MRETURN.
Why it is needed
Today the RETURN instruction in the EVM (Ethereum Virtual Machine) can only return bytes laid out contiguously in memory. But since the introduction of transient storage, many smart contracts use a pattern where data is stored in transient storage to save gas and then returned again in a callback. To return it, the data first has to be read one piece at a time in a loop and copied into memory, which adds the instruction cost of the loop plus memory expansion cost on top. The same inefficiency occurs when returning data that is already in storage. This EIP lets developers choose directly where to return from, eliminating the intermediate step of copying into memory.
What changes
Today
- RETURN can only return contiguous bytes from memory
- Returning data from storage or transient storage first requires copying it into memory with a loop
- The copying process adds instruction cost and memory expansion cost
After EIP-7877
- SRETURN, TRETURN, and RRETURN return directly from storage, transient storage, and the return data buffer
- The existing RETURN is simply renamed to MRETURN; its behavior and gas cost stay the same
- Removing the intermediate copy step means larger gas savings for larger data
Who is affected
- Smart contract developers: Gas can be saved by returning data from transient storage or storage directly, without copying it into memory.
- Compiler teams: The source document explains that the new instructions can be built directly into the Solidity compiler so every contract benefits, and that returns become more explicit, which also makes static analysis easier.
- Client teams: Implementations need to reflect the three new instructions and the renaming of RETURN.
In depth
New instructions and opcode assignment
Three new instructions are added and one existing instruction is renamed. SRETURN (0xf6) returns from storage, TRETURN (0xf7) from transient storage, and RRETURN (0xf8) from the RETURNDATA buffer. The existing RETURN (0xf3) is renamed to MRETURN, and its behavior of returning contiguous bytes from memory, along with its gas cost, remains exactly as it was at the Cancun hard fork.
RRETURN: returning from the return data buffer
RRETURN pops two values from the stack. offset is the starting byte position within the current call's RETURNDATA buffer, and length is the number of bytes to return. It returns the range RETURNDATA[offset : offset + length). Range and error handling are identical to RETURNDATACOPY in EIP-211. If offset + length exceeds RETURNDATASIZE, execution fails, and a zero-length read at the boundary is allowed.
SRETURN and TRETURN: slot serialization rules
SRETURN and TRETURN operate on storage and transient storage respectively, and pop slot (the starting slot number) and length (the number of bytes to return) from the stack. Starting from slot and ascending (slot, slot + 1, …), consecutive slots are serialized, with each slot represented as the same big-endian 32 bytes as a 256-bit word written to memory via MSTORE. The first length bytes of this concatenated byte string are returned. If length is not a multiple of 32, the last slot contributes only the first length % 32 bytes of its 32-byte image, and if length is 0, zero bytes are returned. Reading an uninitialized slot yields 32 zero bytes per slot.
Gas cost
The cost is set to resemble the cost of accessing that data today. SRETURN = (number_of_cold_slots) * 2100 + (number_of_warm_slots * 100), and TRETURN = number_of_slots * 100. RRETURN is the RETURNDATACOPY cost minus the memory expansion cost: with minimum_word_size = (size + 31) / 32, static_gas = 3, dynamic_gas = 3 * minimum_word_size, and the total is static_gas + dynamic_gas.
Design rationale and precedents
Specifying the return location directly removes the intermediate step of writing data to memory first, saving gas at every optimization level, with the savings growing larger as the data grows. The original text cites two precedents. EIP-3855 introduced the PUSH0 opcode to eliminate the workaround of pushing 0 onto the stack, and EIP-6 renamed SUICIDE to SELFDESTRUCT with no change in functionality. It also explains that making the return explicit avoids messy memory allocation, which is also favorable for static analysis.
Compatibility, security, and current status
The original text states that because MRETURN reuses the same opcode and gas cost as the current RETURN, there is no backward compatibility issue. However, due to EOF, it proposes activating this change only in a future EVM version after EOF is fully implemented. On the security side, it states that the change is fully backward compatible and that simpler bytecode reduces the potential attack surface. The current status of this proposal is Stagnant, meaning progress has stalled and the content is not finalized. Inclusion in a fork has also not yet been decided on a core developer call.