EIP-7912 Practical stack manipulation tools (Pragmatic stack manipulation tools)
No call decision · EVM & execution · EIP status Stagnant · created 2025-03-25
Adds SWAP17-24 and DUP17-24, along with SWAPN, DUPN, and EXCHANGE for arbitrary depth, to the EVM, allowing values deeper in the stack to be swapped and duplicated.
Why it is needed
The EVM stacks values in a temporary storage area called the stack and computes with them. The current swap (SWAP) and duplicate (DUP) opcodes can only reach down to the 16th value from the top, so handling values deeper than that requires cumbersome workarounds. The original text explains that, given the characteristics of certain compilers, deeper stack access is a desirable VM feature. However, previous attempts either required code versioning, as with the EVM Object Format (EOF), or risked changing the behavior of already-deployed contracts because of new immediate-value interpretation. This proposal introduces deep stack access through a practical approach that reuses historically agreed-upon instruction semantics, instead of a new and complex encoding or container.
What changes
Today
- The SWAP and DUP opcodes can only handle values down to the 16th position from the top of the stack.
- Deeper stack access required code versioning like EOF
- Using new immediate values risked changing the behavior of already deployed contracts
After EIP-7912
- Fixed-depth instructions up to SWAP24 and DUP24 handle up to the 24th value directly
- SWAPN, DUPN, and EXCHANGE let you swap or duplicate stack elements at arbitrary depth
- Instead of an immediate value, depth is specified by the immediately preceding PUSH instruction, reusing the meaning of existing instructions
Who is affected
- Compiler and contract developers: Compilers can now get the deep stack access they need without code versioning.
- Client teams: Along with implementing the new opcodes, logic must be added to verify that the preceding PUSH executed correctly.
- Users of existing contracts: Per the source, no backwards compatibility issues were found, so already deployed contracts are unaffected.
In depth
Fixed-depth SWAP17 through SWAP24, DUP17 through DUP24
Adds 16 fixed-depth instructions that work the same way as the existing SWAP and DUP. SWAP17 through SWAP24 use opcodes 0xb0 through 0xb7, and DUP17 through DUP24 use 0xb8 through 0xbf. SWAPXX swaps the top element with the top-XX element, and DUPXX duplicates the top-XX element onto the top of the stack. For any of these instructions, referencing an element beyond the current stack length causes a stack underflow and execution ends in an exceptional halt. Unlike the dynamic instructions, no preceding PUSH is needed, so no extra bytes are required.
Dynamic SWAPN, DUPN, and the preceding PUSH1 calling convention
SWAPN (0xc0) and DUPN (0xc1) take the depth N as an argument from the stack. N must be pushed by an immediately preceding PUSH1 instruction, and failing to follow this calling convention or having N equal 0 causes execution to fail with an out-of-gas error. SWAPN pops N and then swaps the new top element with the top-N element, while DUPN pops N and then pushes a copy of the top-(N-1) element onto the top. Compared to the fixed-depth versions, this costs 2 extra bytes for the preceding PUSH1, but in exchange the depth can be specified freely in the code.
EXCHANGE: swapping two elements that are not the top
EXCHANGE (0xc2) takes a single argument X from the stack and splits it into two operands. N is X >> 4, and M is X & 0x0F. X must be pushed by an immediately preceding PUSH2 instruction, and violating the convention or having N or M equal 0 causes execution to fail with an out-of-gas error. After popping X, it swaps the elements at index N-1 and M-1. The reason for counting from 1 is that, just as SWAP1 and DUP1 operate on the top of the stack, it is natural for EXCHANGE(1, 2) to operate on the top and top-1.
Gas cost
All of the new instructions cost 3 gas. The gas for the preceding PUSH instruction is charged separately according to the gas schedule. In other words, using SWAPN, DUPN, or EXCHANGE also incurs the cost of the preceding PUSH1 or PUSH2.
Security: verifying against disguised push data
Client implementers must check that a byte that looks like a preceding PUSH is not actually part of longer push data. The source gives an example of code like 0x6301026001b0 that should produce an error. This can be checked efficiently by testing whether pc-2 is a valid jump destination; if it is, the PUSH instruction executed as expected.
Compatibility and status
The source states that no backwards compatibility issues were found, and the Test Cases section is left as a TODO. This is a Standards Track Core proposal created on March 25, 2025, and its current status is Stagnant, meaning discussion has halted. The content may change if discussion resumes. There is no fork-inclusion decision for this proposal in the call records.