Add PUSH0 (EIP-3855) and KECCAK256 opcodes (#6)

PUSH0 (0x5F):
- Pushes 0 onto the stack for 2 gas (vs PUSH1 0x00 at 3 gas)
- Added in Shanghai upgrade, emitted by modern Solidity compilers
- Trivial implementation, significant gas savings at scale

KECCAK256 (0x20):
- Computes Keccak-256 hash of a memory region
- Static gas: 30 + dynamic: 6 per 32-byte word + memory expansion
- Uses ex_keccak NIF library (Ethereum uses Keccak, NOT SHA3-256)
- Handles empty data, partial words, and zero-padding correctly

Also fixes a bug where dynamic out-of-gas inside opcode handlers
would double-wrap the error status via MachineState.halt.

11 new tests, 110 total (3 doctests + 107 tests), 0 failures.

Author: mw2000

lib/eevm/executor.ex

@@ -67,7 +67,8 @@ defmodule EEVM.Executor do
           {:ok, state_after_gas} ->
             case execute_opcode(opcode, state_after_gas) do
               {:ok, new_state} -> run_loop(new_state)
-              {:error, reason, state} -> MachineState.halt(state, {:error, reason})
+              {:error, :out_of_gas, halted_state} -> halted_state
+              {:error, reason, error_state} -> MachineState.halt(error_state, {:error, reason})
             end
 
           {:error, :out_of_gas, halted_state} ->
@@ -366,6 +367,67 @@ defmodule EEVM.Executor do
     end
   end
 
+  # KECCAK256 (0x20): compute Keccak-256 hash of memory region
+  #
+  # Pops offset and length from stack, reads `length` bytes from memory,
+  # hashes them with Keccak-256, and pushes the 256-bit hash.
+  #
+  # Gas: 30 (static) + 6 per 32-byte word (dynamic) + memory expansion.
+  #
+  # Elixir Learning Note: Ethereum uses Keccak-256, NOT SHA3-256 (NIST
+  # standardized a different padding). We use the `ex_keccak` library
+  # which provides a NIF binding. The result is a 32-byte binary.
+  defp execute_opcode(0x20, state) do
+    with {:ok, offset, s1} <- Stack.pop(state.stack),
+         {:ok, length, s2} <- Stack.pop(s1) do
+      # Charge dynamic gas: 6 per 32-byte word (rounded up)
+      _word_count = div(length + 31, 32)
+      dynamic_cost = Gas.keccak256_dynamic_cost(length)
+
+      # Charge memory expansion gas
+      mem_cost =
+        if length > 0 do
+          Gas.memory_expansion_cost(Memory.size(state.memory), offset, length)
+        else
+          0
+        end
+
+      case MachineState.consume_gas(state, dynamic_cost + mem_cost) do
+        {:ok, state_after_gas} ->
+          # Read bytes from memory
+          {data, updated_memory} =
+            if length > 0 do
+              Memory.read_bytes(state_after_gas.memory, offset, length)
+            else
+              {<<>>, state_after_gas.memory}
+            end
+
+          hash = ExKeccak.hash_256(data)
+          <<hash_int::unsigned-big-256>> = hash
+          {:ok, new_stack} = Stack.push(s2, hash_int)
+
+          {:ok,
+           %{state_after_gas | stack: new_stack, memory: updated_memory}
+           |> MachineState.advance_pc()}
+
+        {:error, :out_of_gas, halted} ->
+          {:error, :out_of_gas, halted}
+      end
+    else
+      {:error, reason} -> {:error, reason, state}
+    end
+  end
+
+  # PUSH0 (0x5F): push zero onto the stack — EIP-3855
+  #
+  # The simplest opcode added in the Shanghai upgrade. Saves gas vs
+  # PUSH1 0x00 (costs 2 instead of 3). Modern Solidity compilers emit
+  # this whenever they need a zero value on the stack.
+  defp execute_opcode(0x5F, state) do
+    {:ok, new_stack} = Stack.push(state.stack, 0)
+    {:ok, %{state | stack: new_stack} |> MachineState.advance_pc()}
+  end
+
   # POP (0x50): discard top of stack
   defp execute_opcode(0x50, state) do
     case Stack.pop(state.stack) do

lib/eevm/gas.ex

@@ -200,6 +200,9 @@ defmodule EEVM.Gas do
   # SSTORE
   def static_cost(0x55), do: @gas_sstore
 
+  # PUSH0 (0x5F) — EIP-3855
+  def static_cost(0x5F), do: @gas_base
+
   # PUSH1–PUSH32 (0x60–0x7F)
   def static_cost(op) when op >= 0x60 and op <= 0x7F, do: @gas_very_low
 

lib/eevm/opcodes.ex

@@ -53,6 +53,9 @@ defmodule EEVM.Opcodes do
   # Environment opcodes (0x30–0x48)
   @address 0x30
   @balance 0x31
+  @keccak256 0x20
+  @push0 0x5F
+
   @origin 0x32
   @caller 0x33
   @callvalue 0x34
@@ -125,6 +128,7 @@ defmodule EEVM.Opcodes do
   def info(@mulmod), do: {:ok, %{name: "MULMOD", inputs: 3, outputs: 1}}
   def info(@exp), do: {:ok, %{name: "EXP", inputs: 2, outputs: 1}}
   def info(@signextend), do: {:ok, %{name: "SIGNEXTEND", inputs: 2, outputs: 1}}
+  def info(@keccak256), do: {:ok, %{name: "KECCAK256", inputs: 2, outputs: 1}}
 
   def info(@lt), do: {:ok, %{name: "LT", inputs: 2, outputs: 1}}
   def info(@gt), do: {:ok, %{name: "GT", inputs: 2, outputs: 1}}
@@ -164,6 +168,8 @@ defmodule EEVM.Opcodes do
   def info(@basefee), do: {:ok, %{name: "BASEFEE", inputs: 0, outputs: 1}}
   def info(@gas_), do: {:ok, %{name: "GAS", inputs: 0, outputs: 1}}
 
+  def info(@push0), do: {:ok, %{name: "PUSH0", inputs: 0, outputs: 1}}
+
   def info(@pop), do: {:ok, %{name: "POP", inputs: 1, outputs: 0}}
   def info(@mload), do: {:ok, %{name: "MLOAD", inputs: 1, outputs: 1}}
   def info(@mstore), do: {:ok, %{name: "MSTORE", inputs: 2, outputs: 0}}

mix.exs

@@ -13,11 +13,14 @@ defmodule EEVM.MixProject do
 
   def application do
     [
-      extra_applications: [:logger]
+      extra_applications: [:logger, :crypto]
     ]
   end
 
   defp deps do
-    []
+    [
+      # Keccak-256 hash (Ethereum uses Keccak, not SHA3-256)
+      {:ex_keccak, "~> 0.7"}
+    ]
   end
 end

mix.lock

@@ -0,0 +1,5 @@
+%{
+  "castore": {:hex, :castore, "1.0.17", "4f9770d2d45fbd91dcf6bd404cf64e7e58fed04fadda0923dc32acca0badffa2", [:mix], [], "hexpm", "12d24b9d80b910dd3953e165636d68f147a31db945d2dcb9365e441f8b5351e5"},
+  "ex_keccak": {:hex, :ex_keccak, "0.7.8", "be1cf194d3158f0a305eaed0334e478d0d0f2c827e7c1f8f0e1e2a667da5a8ac", [:mix], [{:rustler, ">= 0.0.0", [hex: :rustler, repo: "hexpm", optional: true]}, {:rustler_precompiled, "~> 0.8", [hex: :rustler_precompiled, repo: "hexpm", optional: false]}], "hexpm", "52de5b42b718df2534fb9a55780d8a05bbaea539f867c3e7c0a8e7e1d5f149d9"},
+  "rustler_precompiled": {:hex, :rustler_precompiled, "0.8.4", "700a878312acfac79fb6c572bb8b57f5aae05fe1cf70d34b5974850bbf2c05bf", [:mix], [{:castore, "~> 0.1 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: false]}, {:rustler, "~> 0.23", [hex: :rustler, repo: "hexpm", optional: true]}], "hexpm", "3b33d99b540b15f142ba47944f7a163a25069f6d608783c321029bc1ffb09514"},
+}

test/eevm_test.exs

@@ -808,4 +808,101 @@ defmodule EEVMTest do
       assert result.gas == 1000 - 5
     end
   end
+
+  # ── PUSH0 & KECCAK256 Tests ────────────────────────────────────────
+
+  describe "PUSH0 (EIP-3855)" do
+    test "pushes 0 onto the stack" do
+      # PUSH0, STOP
+      code = <<0x5F, 0x00>>
+      result = EEVM.execute(code)
+      assert EEVM.stack_values(result) == [0]
+    end
+
+    test "PUSH0 costs 2 gas (base)" do
+      code = <<0x5F, 0x00>>
+      result = EEVM.execute(code, gas: 1000)
+      assert result.gas == 1000 - 2
+    end
+
+    test "PUSH0 + PUSH0 + ADD = 0" do
+      # PUSH0, PUSH0, ADD, STOP
+      code = <<0x5F, 0x5F, 0x01, 0x00>>
+      result = EEVM.execute(code)
+      assert EEVM.stack_values(result) == [0]
+    end
+
+    test "PUSH0 is cheaper than PUSH1 0" do
+      # PUSH0 costs 2, PUSH1 costs 3
+      push0_code = <<0x5F, 0x00>>
+      push1_code = <<0x60, 0, 0x00>>
+      r0 = EEVM.execute(push0_code, gas: 1000)
+      r1 = EEVM.execute(push1_code, gas: 1000)
+      assert r0.gas > r1.gas
+    end
+
+    test "disassembles as PUSH0" do
+      [{0, name, nil}] = EEVM.disassemble(<<0x5F>>)
+      assert name == "PUSH0"
+    end
+  end
+
+  describe "KECCAK256" do
+    test "hashes empty data" do
+      # PUSH1 0 (length), PUSH1 0 (offset), KECCAK256, STOP
+      code = <<0x60, 0, 0x60, 0, 0x20, 0x00>>
+      result = EEVM.execute(code)
+      assert result.status == :stopped
+      # Keccak-256 of empty data
+      expected = ExKeccak.hash_256(<<>>)
+      <<expected_int::unsigned-big-256>> = expected
+      assert EEVM.stack_values(result) == [expected_int]
+    end
+
+    test "hashes data stored in memory" do
+      # Store 0xFF at memory[0], then hash the first byte
+      # PUSH1 0xFF, PUSH1 0, MSTORE8, PUSH1 1 (length), PUSH1 0 (offset), KECCAK256, STOP
+      code = <<0x60, 0xFF, 0x60, 0, 0x53, 0x60, 1, 0x60, 0, 0x20, 0x00>>
+      result = EEVM.execute(code)
+      assert result.status == :stopped
+      expected = ExKeccak.hash_256(<<0xFF>>)
+      <<expected_int::unsigned-big-256>> = expected
+      assert EEVM.stack_values(result) == [expected_int]
+    end
+
+    test "static gas is 30 + dynamic 6 per word" do
+      # Hash 32 bytes (1 word): PUSH1 32, PUSH1 0, KECCAK256, STOP
+      # Static (charged in run_loop): 30
+      # Dynamic: 6 * 1 word = 6
+      # Memory expansion: 0→32 bytes = 3 gas
+      # Other: PUSH1=3 + PUSH1=3 + STOP=0
+      code = <<0x60, 32, 0x60, 0, 0x20, 0x00>>
+      result = EEVM.execute(code, gas: 10_000)
+      # Total: 3 + 3 + 30 + 6 + 3 + 0 = 45
+      assert result.gas == 10_000 - 45
+    end
+
+    test "dynamic gas scales with data size" do
+      # Hash 64 bytes (2 words) vs 32 bytes (1 word)
+      # Extra word costs 6 more gas
+      code1 = <<0x60, 32, 0x60, 0, 0x20, 0x00>>
+      code2 = <<0x60, 64, 0x60, 0, 0x20, 0x00>>
+      r1 = EEVM.execute(code1, gas: 100_000)
+      r2 = EEVM.execute(code2, gas: 100_000)
+      # r2 should use 6 more gas (1 extra word) + some memory expansion
+      assert r1.gas > r2.gas
+    end
+
+    test "out of gas on large hash" do
+      # Try to hash 1024 bytes with only 100 gas
+      code = <<0x61, 0x04, 0x00, 0x60, 0, 0x20, 0x00>>
+      result = EEVM.execute(code, gas: 100)
+      assert result.status == :out_of_gas
+    end
+
+    test "disassembles as KECCAK256" do
+      [{0, name, nil}] = EEVM.disassemble(<<0x20>>)
+      assert name == "KECCAK256"
+    end
+  end
 end