Modularize executor into opcode modules and reorganize project structure (#7)

* Modularize executor into opcode modules and reorganize project structure

- Split monolithic executor.ex (942 lines) into thin dispatcher + 9 opcode modules under opcodes/
- Move Transaction, Block, Contract into context/ namespace (EEVM.Context.*)
- Split monolithic test file into per-module test files
- Add comprehensive @moduledoc, @doc, and @SPEC to all new modules
- Update README architecture section and remove completed roadmap

* Fix formatting lint issues in opcode modules

Author: mw2000

README.md

@@ -26,25 +26,44 @@ iex> EEVM.disassemble(<<0x60, 0x01, 0x60, 0x02, 0x01, 0x00>>)
 | **Arithmetic** | `ADD` `MUL` `SUB` `DIV` `SDIV` `MOD` `SMOD` `ADDMOD` `MULMOD` `EXP` `SIGNEXTEND` |
 | **Comparison** | `LT` `GT` `SLT` `SGT` `EQ` `ISZERO` |
 | **Bitwise** | `AND` `OR` `XOR` `NOT` `BYTE` `SHL` `SHR` `SAR` |
-| **Stack** | `POP` `PUSH1`–`PUSH32` `DUP1`–`DUP16` `SWAP1`–`SWAP16` |
+| **Crypto** | `KECCAK256` |
+| **Stack** | `POP` `PUSH0` `PUSH1`–`PUSH32` `DUP1`–`DUP16` `SWAP1`–`SWAP16` |
 | **Memory** | `MLOAD` `MSTORE` `MSTORE8` `MSIZE` |
+| **Storage** | `SLOAD` `SSTORE` |
+| **Environment** | `ADDRESS` `BALANCE` `ORIGIN` `CALLER` `CALLVALUE` `CALLDATALOAD` `CALLDATASIZE` `CALLDATACOPY` `CODESIZE` `GASPRICE` `RETURNDATASIZE` `BLOCKHASH` `COINBASE` `TIMESTAMP` `NUMBER` `PREVRANDAO` `GASLIMIT` `CHAINID` `SELFBALANCE` `BASEFEE` `GAS` |
 | **Control Flow** | `JUMP` `JUMPI` `JUMPDEST` `PC` |
 | **System** | `STOP` `RETURN` `REVERT` `INVALID` |
 
 ## Architecture
 
 ```
 lib/
-├── eevm.ex              # Public API — execute, disassemble, inspect
+├── eevm.ex                    # Public API — execute, disassemble, inspect
 └── eevm/
-    ├── stack.ex          # LIFO stack (1024 depth, uint256 values)
-    ├── memory.ex         # Byte-addressable linear memory
-    ├── machine_state.ex  # Execution state (PC, stack, memory, gas)
-    ├── opcodes.ex        # Opcode byte → name + stack metadata
-    └── executor.ex       # Fetch-decode-execute loop
+    ├── executor.ex            # Thin dispatcher — fetch, decode, route to opcode modules
+    ├── machine_state.ex       # Execution state (PC, stack, memory, gas)
+    ├── stack.ex               # LIFO stack (1024 depth, uint256 values)
+    ├── memory.ex              # Byte-addressable linear memory
+    ├── storage.ex             # Persistent key-value storage
+    ├── gas.ex                 # Gas metering and per-opcode costs
+    ├── opcodes.ex             # Opcode byte → name + stack metadata
+    ├── context/
+    │   ├── transaction.ex     # Transaction context (origin, gas price)
+    │   ├── block.ex            # Block context (coinbase, timestamp, number)
+    │   └── contract.ex         # Contract context (address, caller, value, calldata)
+    └── opcodes/
+        ├── helpers.ex         # Shared utilities (signing, modular exponentiation)
+        ├── arithmetic.ex      # ADD, MUL, SUB, DIV, MOD, EXP, SIGNEXTEND
+        ├── comparison.ex      # LT, GT, SLT, SGT, EQ, ISZERO
+        ├── bitwise.ex         # AND, OR, XOR, NOT, BYTE, SHL, SHR, SAR
+        ├── crypto.ex          # KECCAK256
+        ├── stack_memory_storage.ex  # POP, MLOAD, MSTORE, SLOAD, SSTORE, MSIZE
+        ├── environment.ex     # ADDRESS, CALLER, CALLVALUE, CALLDATALOAD, ...
+        ├── control_flow.ex    # JUMP, JUMPI, PUSH0–PUSH32, DUP, SWAP
+        └── system.ex          # STOP, RETURN, REVERT, INVALID
 ```
 
-The EVM is a **stack machine**. The executor reads one opcode at a time from bytecode, pops operands from the stack, computes, and pushes results back. All values are unsigned 256-bit integers. Memory is a separate byte-addressable space that expands on demand.
+The EVM is a **stack machine**. The executor reads one opcode at a time from bytecode and dispatches to the appropriate opcode module. Each module pops operands from the stack, computes, and pushes results back. All values are unsigned 256-bit integers. Memory is a separate byte-addressable space that expands on demand.
 
 The architecture is intentionally flat — no processes, no GenServers, no OTP. Pure functions in, state out. This makes it easy to follow the execution flow and understand both the EVM and Elixir's functional style.
 
@@ -79,16 +98,6 @@ This project is designed as a learning tool. Each module demonstrates specific E
 - **Module attributes** — `@constants` and `@spec` type annotations
 - **Binary pattern matching** — Parsing raw bytecode with `<<>>` syntax
 
-## Roadmap
-
-- [ ] Gas metering (per-opcode costs)
-- [ ] Storage (`SLOAD` / `SSTORE`)
-- [ ] Environment opcodes (`CALLER`, `CALLVALUE`, `CALLDATA*`)
-- [ ] `LOG0`–`LOG4` events
-- [ ] Contract creation and `CALL`
-- [ ] Precompiled contracts
-- [ ] EVM test suite compatibility (ethereum/tests)
-
 ## License
 
 MIT

lib/eevm/block.ex lib/eevm/context/block.exlib/eevm/block.ex renamed to lib/eevm/context/block.ex

@@ -1,4 +1,4 @@
-defmodule EEVM.Block do
+defmodule EEVM.Context.Block do
   @moduledoc """
   Block-level context — information about the block being executed.
 
@@ -64,7 +64,7 @@ defmodule EEVM.Block do
 
   ## Example
 
-      iex> block = EEVM.Block.new(number: 18_000_000, chain_id: 1)
+      iex> block = EEVM.Context.Block.new(number: 18_000_000, chain_id: 1)
       iex> block.number
       18000000
   """

lib/eevm/contract.ex lib/eevm/context/contract.exlib/eevm/contract.ex renamed to lib/eevm/context/contract.ex

@@ -1,4 +1,4 @@
-defmodule EEVM.Contract do
+defmodule EEVM.Context.Contract do
   @moduledoc """
   Contract/message-level context — the current call frame's environment.
 
@@ -24,7 +24,7 @@ defmodule EEVM.Contract do
 
   - `caller` (CALLER/msg.sender) = who directly called this contract.
     Changes with each nested CALL.
-  - `origin` (ORIGIN/tx.origin, in `EEVM.Transaction`) = the EOA that
+  - `origin` (ORIGIN/tx.origin, in `EEVM.Context.Transaction`) = the EOA that
     signed the transaction. Never changes.
 
   Example: EOA → Contract A → Contract B
@@ -62,7 +62,7 @@ defmodule EEVM.Contract do
 
   ## Example
 
-      iex> contract = EEVM.Contract.new(caller: 0xDEAD, callvalue: 1000)
+      iex> contract = EEVM.Context.Contract.new(caller: 0xDEAD, callvalue: 1000)
       iex> contract.caller
       0xDEAD
   """

lib/eevm/transaction.ex lib/eevm/context/transaction.exlib/eevm/transaction.ex renamed to lib/eevm/context/transaction.ex

@@ -1,4 +1,4 @@
-defmodule EEVM.Transaction do
+defmodule EEVM.Context.Transaction do
   @moduledoc """
   Transaction-level context — information about the original transaction.
 
@@ -20,7 +20,7 @@ defmodule EEVM.Transaction do
   ### Origin vs Caller
 
   `origin` is always the EOA that signed the transaction — it never changes,
-  even through nested contract calls. `caller` (in `EEVM.Contract`) is the
+  even through nested contract calls. `caller` (in `EEVM.Context.Contract`) is the
   *direct* caller of the current frame and changes with each CALL.
 
   ## Elixir Learning Notes
@@ -47,7 +47,7 @@ defmodule EEVM.Transaction do
 
   ## Example
 
-      iex> tx = EEVM.Transaction.new(origin: 0xDEAD, gasprice: 20_000_000_000)
+      iex> tx = EEVM.Context.Transaction.new(origin: 0xDEAD, gasprice: 20_000_000_000)
       iex> tx.origin
       0xDEAD
   """