feat(l1): add interactive REPL

Cargo.toml

@@ -23,6 +23,7 @@ members = [
   "crates/vm/levm",
   "crates/vm/levm/runner",
   "crates/common/config",
+  "tooling/repl",
   "test",
 ]
 exclude = ["crates/vm/levm/bench/revm_comparison"]
@@ -74,6 +75,7 @@ ethrex-guest-program = { path = "./crates/guest-program" }
 ethrex-storage-rollup = { path = "./crates/l2/storage" }
 ethrex = { path = "./cmd/ethrex" }
 ethrex-l2-rpc = { path = "./crates/l2/networking/rpc" }
+ethrex-repl = { path = "./tooling/repl" }
 
 tracing = { version = "0.1", features = ["log"] }
 tracing-subscriber = { version = "0.3.0", features = ["env-filter"] }

Dockerfile

@@ -22,6 +22,7 @@ COPY crates ./crates
 COPY metrics ./metrics
 COPY cmd ./cmd
 COPY test ./test
+COPY tooling ./tooling
 COPY Cargo.* .
 COPY .cargo/ ./.cargo
 

cmd/ethrex/Cargo.toml

@@ -20,6 +20,7 @@ ethrex-l2-common = { workspace = true, optional = true }
 ethrex-l2-rpc = { workspace = true, optional = true }
 ethrex-metrics = { path = "../../crates/blockchain/metrics" }
 ethrex-p2p.workspace = true
+ethrex-repl.workspace = true
 ethrex-prover = { workspace = true, optional = true, features = ["l2"] }
 ethrex-rlp.workspace = true
 ethrex-rpc.workspace = true

cmd/ethrex/cli.rs

@@ -454,6 +454,20 @@ pub enum Subcommand {
         )]
         genesis_path: PathBuf,
     },
+    #[command(name = "repl", about = "Interactive REPL for Ethereum JSON-RPC")]
+    Repl {
+        /// JSON-RPC endpoint URL
+        #[arg(short = 'e', long, default_value = "http://localhost:8545")]
+        endpoint: String,
+
+        /// Path to command history file
+        #[arg(long, default_value = "~/.ethrex/history")]
+        history_file: String,
+
+        /// Execute a single command and exit
+        #[arg(short = 'x', long)]
+        execute: Option<String>,
+    },
     #[cfg(feature = "l2")]
     #[command(name = "l2")]
     L2(crate::l2::L2Command),
@@ -532,6 +546,13 @@ impl Subcommand {
                 let state_root = genesis.compute_state_root();
                 println!("{state_root:#x}");
             }
+            Subcommand::Repl {
+                endpoint,
+                history_file,
+                execute,
+            } => {
+                ethrex_repl::run(endpoint, history_file, execute).await;
+            }
             #[cfg(feature = "l2")]
             Subcommand::L2(command) => command.run().await?,
         }

docs/CLI.md

@@ -15,6 +15,7 @@ Commands:
   import-bench        Import blocks to the database for benchmarking
   export              Export blocks in the current chain into a file in rlp encoding
   compute-state-root  Compute the state root from a genesis file
+  repl                Interactive REPL for Ethereum JSON-RPC
   help                Print this message or the help of the given subcommand(s)
 
 Options:

docs/SUMMARY.md

@@ -122,6 +122,7 @@
 - [Debugging solidity with ethrex](./vm/levm/debug.md)
 - [Re-execute Ethereum with ethrex](./ethrex_replay/ethrex_replay.md)
   - [FAQ](./ethrex_replay/faq.md)
+- [Interactive REPL](./developers/repl.md)
 - [CLI reference](./CLI.md)
 - [Release Process](./developers/release-process.md)
 - [Troubleshooting]()

docs/developers/repl.md

@@ -0,0 +1,131 @@
+# Interactive REPL
+
+The ethrex REPL is an interactive Read-Eval-Print Loop for Ethereum JSON-RPC. It lets you query any Ethereum node directly from your terminal using a concise `namespace.method` syntax.
+
+## Quick Start
+
+```bash
+# Via the ethrex binary
+ethrex repl
+
+# Connect to a specific endpoint
+ethrex repl -e https://eth.llamarpc.com
+
+# Execute a single command and exit
+ethrex repl -x "eth.blockNumber"
+```
+
+## CLI Options
+
+```
+ethrex repl [OPTIONS]
+
+Options:
+  -e, --endpoint <URL>       JSON-RPC endpoint [default: http://localhost:8545]
+      --history-file <PATH>  Path to command history file [default: ~/.ethrex/history]
+  -x, --execute <COMMAND>    Execute a single command and exit
+```
+
+## RPC Commands
+
+Type `namespace.method` with arguments separated by spaces or in parentheses:
+
+```
+> eth.blockNumber
+68943
+
+> eth.getBalance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+1000000000000000000
+
+> eth.getBalance("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "latest")
+1000000000000000000
+
+> eth.getBlockByNumber 100 true
+┌─────────────────────────────────────────┐
+│            number   100                 │
+│         timestamp   1438270128          │
+│  ...                                    │
+└─────────────────────────────────────────┘
+```
+
+## Supported Namespaces
+
+| Namespace | Methods | Description |
+|-----------|--------:|-------------|
+| `eth`     | 30      | Accounts, blocks, transactions, filters, gas, proofs |
+| `debug`   | 8       | Raw headers/blocks/transactions/receipts, tracing |
+| `admin`   | 4       | Node info, peers, log level, add peer |
+| `net`     | 2       | Network ID, peer count |
+| `web3`    | 1       | Client version |
+| `txpool`  | 2       | Transaction pool content and status |
+
+Type `.help` to list all namespaces, `.help eth` to list methods in a namespace, or `.help eth.getBalance` for detailed method documentation.
+
+## ENS Name Resolution
+
+Any command that accepts an address also accepts ENS names:
+
+```
+> eth.getBalance vitalik.eth
+Resolved vitalik.eth -> 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+1000000000000000000
+```
+
+Resolution is done on-chain by querying the ENS registry at `0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e`. This works against any endpoint connected to Ethereum mainnet.
+
+## Utility Functions
+
+| Function | Example | Description |
+|----------|---------|-------------|
+| `toWei` | `toWei 1.5 ether` → `1500000000000000000` | Convert to wei |
+| `fromWei` | `fromWei 1000000000 gwei` → `1` | Convert from wei |
+| `toHex` | `toHex 255` → `0xff` | Decimal to hex |
+| `fromHex` | `fromHex 0xff` → `255` | Hex to decimal |
+| `keccak256` | `keccak256 0x68656c6c6f` → `0x1c8a...` | Keccak-256 hash |
+| `toChecksumAddress` | `toChecksumAddress 0xd8da...` → `0xd8dA...` | EIP-55 checksum |
+| `isAddress` | `isAddress 0xd8dA...` → `true` | Validate address format |
+
+Units for `toWei`/`fromWei`: `wei`, `gwei`, `ether` (or `eth`).
+
+## Built-in Commands
+
+| Command | Description |
+|---------|-------------|
+| `.help [namespace\|command]` | Show help |
+| `.exit` / `.quit` | Exit the REPL |
+| `.clear` | Clear the screen |
+| `.connect <url>` | Show or change endpoint |
+| `.history` | Show history file path |
+
+## Other Features
+
+- **Tab completion** for namespaces, methods, block tags, and utilities
+- **Parameter hints** shown after typing a full method name
+- **Multi-line input** — unbalanced `{}` or `[]` automatically continues to the next line
+- **Persistent history** saved to `~/.ethrex/history`
+- **Formatted output** — addresses, hashes, hex quantities, and nested objects are colored and auto-formatted
+
+## Using with ethrex dev mode
+
+The REPL pairs well with [ethrex dev mode](./l1/dev-mode.md). Start a local node, then connect the REPL to it:
+
+```bash
+# Terminal 1: start ethrex in dev mode
+ethrex --dev
+
+# Terminal 2: connect the REPL (default endpoint is localhost:8545)
+ethrex repl
+```
+
+## Running from source
+
+```bash
+# As an ethrex subcommand
+cargo run -p ethrex -- repl
+
+# Or directly
+cargo run -p ethrex-repl
+
+# Run tests
+cargo test -p ethrex-repl
+```