Welcome

Before entering Run#

evm.Call() sets up the execution context before handing off to the interpreter:

1
evm.Call(sender, to, input, gas, value)
2
  1. depth > 1024?           → prevent infinite recursion
3
  2. sufficient balance?      → check caller can afford value transfer
4
  3. snapshot state           → for rollback on error
5
  4. is precompile?           → call Go function directly, skip interpreter
6
  5. load target bytecode     → resolveCode(addr)
7
  6. create Contract object   → packages caller, address, gas, code
8
  7. enter Run()

On error, RevertToSnapshot rolls back state. If the error is REVERT, remaining gas is returned; for other errors (e.g., OOG), all gas is consumed.

Inside Run#

Upon entering Run(), per-call-frame resources are allocated:

1
evm.depth++                    // call depth +1
2
stack  = newstack()            // from sync.Pool
3
mem    = NewMemory()           // fresh memory buffer
4
scope  = &ScopeContext{Memory: mem, Stack: stack, Contract: contract}
5
pc     = 0                     // program counter starts at 0

Then the main loop runs, with 7 steps per iteration:

1
for {
2
    ① op = contract.GetOp(pc)           // fetch bytecode[pc] as OpCode
3
    ② operation = jumpTable[op]          // lookup: get execute func, gas, stack bounds
4
    ③ validate stack: enough elements? would overflow?
5
    ④ deduct constantGas (fixed cost, e.g., ADD=3)
6
    ⑤ if dynamicGas: compute + deduct (e.g., SLOAD cold/warm cost)
7
    ⑥ if memorySize: expand memory + charge memory gas
8
    ⑦ operation.execute(&pc, evm, scope)  // execute!
9
    pc++
10
}

Walking through an ADD instruction:

1
① pc=5, bytecode[5] = 0x01 (ADD)
2
② jumpTable[0x01] = {execute: opAdd, constantGas: 3, minStack: 2, maxStack: 1025}
3
③ stack has 4 elements ≥ 2 ✓, 4-2+1=3 ≤ 1024 ✓
4
④ contract.Gas -= 3
5
⑤ ADD has no dynamicGas — skip
6
⑥ ADD doesn't touch memory — skip
7
⑦ opAdd: pop two numbers, add them, leave result on stack top
8
   pc++ → pc=6

How the loop exits#

• STOP / RETURN — return sentinel errStopToken, Run() clears it to nil, normal exit
• REVERT — return error + return data, caller rolls back state but refunds remaining gas
• ErrOutOfGas — not enough gas to deduct, loop breaks
• ErrStackUnderflow/Overflow — stack validation fails
• JUMP to invalid position — ErrInvalidJump

On frame exit, the stack is returned to the pool, memory is freed, and evm.depth--.

Special handling for JUMP#

Most opcodes just let pc++ advance to the next instruction. But JUMP and JUMPI modify *pc directly inside their execute function:

1
func opJump(pc *uint64, evm *EVM, scope *ScopeContext) ([]byte, error) {
2
    pos := scope.Stack.pop()
3
    if !scope.Contract.validJumpdest(&pos) {
4
        return nil, ErrInvalidJump    // can't jump into PUSH data
5
    }
6
    *pc = pos.Uint64() - 1            // -1 because the loop does pc++ after
7
    return nil, nil
8
}

validJumpdest uses a bitmap to mark which byte positions are real opcodes (vs. embedded data inside PUSH instructions), preventing jumps into the middle of data.

Call — the standard invocation#

1
Contract A calls Contract B
2
├─ Executes B's code
3
├─ Runs in B's context (msg.sender = A, address = B)
4
├─ Can transfer ETH
5
└─ Can modify B's storage

A straightforward “I call you.” B sees msg.sender as A, address(this) as B.

StaticCall — read-only invocation#

1
Contract A static-calls Contract B
2
├─ Executes B's code
3
├─ readOnly = true
4
├─ Cannot transfer ETH (no value parameter)
5
├─ Cannot modify any state (SSTORE, LOG, CREATE, SELFDESTRUCT all forbidden)
6
└─ Violation → ErrWriteProtection

Used for view / pure function calls. Guarantees the call produces no side effects.

DelegateCall — “borrow the code”#

1
Contract A delegate-calls Contract B
2
├─ Executes B's code
3
├─ But runs in A's context!
4
│   ├─ msg.sender = A's caller (not A)
5
│   ├─ address(this) = A (not B)
6
│   └─ storage reads/writes target A's storage (not B's)
7
├─ Cannot transfer ETH
8
└─ B's code operates on A's state

This is the foundation of the proxy pattern. Proxy contract A holds no business logic — it delegate-calls logic contract B, but all state changes happen on A.

The key difference in code:

1
// Call: caller=A, address=B
2
contract := NewContract(A, B, value, gas, ...)
3

4
// DelegateCall: caller=A's caller, address=A
5
contract := NewContract(originCaller, A, value, gas, ...)

Comparison table#

Create / Create2#

Contract creation takes a different path but follows a similar structure:

1. Compute new address — CREATE: keccak256(rlp([sender, nonce])). CREATE2: keccak256(0xff ++ sender ++ salt ++ keccak256(initCode)).
2. Collision check — target address must not have non-zero nonce, non-empty code, or non-empty storage.
3. Create account, transfer value, set nonce to 1.
4. Execute init code (constructor). The returned bytes become the deployed code.
5. Verify code size ≤ 24,576 bytes.
6. Charge code storage gas: len(code) × 200.

Three values#

Gas calculation is based on comparing three values:

1
original — the slot's value at the start of the transaction (read from disk)
2
current  — the present value (may have been modified earlier in this transaction)
3
new      — the value you're writing now

Scenario breakdown#

Scenario 1: current == new (writing the same value)

1
Slot is currently 42, you write 42
2
→ 100 gas (warm read price)

Nothing changes, minimal charge.

Scenario 2: original == current, original == 0 (zero → non-zero)

1
Slot has never been used, you write 42
2
→ 20,000 gas

Creates a brand-new node in the trie. Most expensive.

Scenario 3: original == current, original != 0 (non-zero → different non-zero)

1
Slot is 42, you change it to 100
2
→ 2,900 gas

Node already exists, just updating the value.

Scenario 4: original == current, new == 0 (non-zero → zero)

1
Slot is 42, you clear it to 0
2
→ 2,900 gas + refund

Deletes a trie node, rewarded with a refund.

Scenario 5: original != current (dirty slot — already modified in this transaction)

1
Transaction start: slot = 42  (original)
2
First write:       slot = 100 (current, cost 2,900 gas)
3
Second write:      slot = 200 (new)
4
→ Second write costs only 100 gas (warm read)

You already paid the big price for this slot’s change on the first write. Subsequent modifications are charged the minimum.

Warm / Cold stacking#

All scenarios above also stack with EIP-2929 warm/cold rules:

1
First access to this slot (cold) → additional +2,100 gas
2
Subsequent access (warm)         → no extra charge

So a completely cold slot written from zero to non-zero: 2,100 (cold) + 20,000 (set) = 22,100 gas.

Why this design#

The core goal is net gas metering. If a transaction writes the same slot 5 times, you only pay for “the difference between the final result and the original value,” not for 5 separate writes. This encourages contract developers to freely use temporary variables (e.g., updating a slot in a loop) without worrying about gas explosion.

The refund mechanism follows the same philosophy: clearing a slot frees a trie node, so you get a refund. But if you clear a slot and then write it back to non-zero in the same transaction, the refund is canceled — because the net effect is no node was freed.