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

After EIP-7877

Who is affected

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.

Original EIP · ← EIPs