EIP-5450 EOF stack validation (EOF - Stack Validation)

No call decision · EVM & execution · EIP status Stagnant · created 2022-08-12

A proposal that pre-validates a function's stack usage when EOF (EVM Object Format) code is deployed, eliminating most stack underflow/overflow checks during execution.

Why it is needed

Currently, the EVM checks every time an instruction is executed whether the stack is empty with nothing left to pop (underflow) or has grown too large and overflowed. This check accumulates as an execution cost, and it also fails to prevent the deployment of dead code that can never actually be reached along any path. By structuring code with EOF, the entire code can be analyzed once before deployment to prove in advance that the stack cannot overflow along any execution path. This removes the need to repeat the check on every execution, and also helps compilers analyze EVM code faster or perform ahead-of-time (AOT) or just-in-time (JIT) compilation.

What changes

Today

After EIP-5450

Who is affected

In depth

Validation target and preconditions

This EIP depends on the operand stack and type section concepts defined by EIP-4750. Each code section is validated independently. The "operand stack height" referred to here means only the number of stack values the current function can access, excluding values from the caller's frame. The validation procedure itself does not require an actual stack implementation; only tracking the height is necessary.

Two-stage validation

The first-stage validation defined by EIP-3670, EIP-4200, and EIP-4750 independently checks whether each instruction's opcode and immediate value are valid. The second-stage validation added by this EIP performs control flow analysis to check stack usage. Terminating instructions are divided into function termination (RETF, JUMPF) and call frame termination (STOP, RETURN, RETURNCODE, REVERT, INVALID).

Tracking stack height ranges

Code is checked with a single linear scan. For each instruction, stack_height_min and stack_height_max are recorded. CALLF requires at least as many inputs as the called function needs, RETF must exactly match the function's output count, and JUMPF's requirement differs depending on whether it is a returning function. Other instructions require at least as many inputs as they themselves need.

Overflow checks for CALLF and JUMPF

These two instructions alone retain overflow checks at runtime. Validation fails if the recorded upper bound of stack height exceeds 1024 minus the target function's max_stack_increase. This guarantees that all other instructions are safe without any runtime overflow check at all.

Handling forward and backward jumps, basic block ordering

Forward jumps (RJUMP/RJUMPI/RJUMPV with an offset of 0 or greater) may arrive at the same point from multiple paths, in which case the minimum/maximum ranges are merged and recorded. Backward jumps (negative offset) only pass if they exactly match the height recorded at the destination. To handle this with a single linear scan, the code generator must arrange basic blocks in reverse postorder, so that no block is referenced only by a backward jump.

Properties guaranteed by validated code

Code that passes this validation has no unreachable instructions and no instructions reachable only via a backward jump. Stack underflow cannot occur, and overflow is only possible at CALLF and JUMPF. Backward jump targets always execute at the same stack height, which prevents loops that endlessly grow or shrink the stack. The code's final instruction must be a terminating instruction or RJUMP.

RETF's clean-stack requirement and rejection of a looser alternative

When RETF executes, the stack in the current function context must have left exactly as many values as the function's output count. A relaxed approach that clears and cleans up leftover stack values was also possible, but was not adopted because its cost is not constant. However, it is noted that this relaxation is backwards compatible and could be introduced separately later. A stricter alternative that fully fixes the stack height across all code paths was also considered, but was rejected because it breaks a common compilation pattern where branches such as asserts jump to a shared termination helper from different stack heights.

Scope of application and status

This change alters consensus rules and therefore requires a network upgrade. However, it is stated that it applies only to EOF1-format code and has no effect on existing legacy bytecode, so there is no backwards compatibility risk. It requires EIP-3540, 3670, 4200, and 4750 as prerequisites. This EIP's status is currently Stagnant, meaning discussion has stalled and inclusion in a fork has not yet been decided.

Original EIP · ← EIPs