docs(l2): improve ethrex-replay docs (#3498)

> [!CAUTION]
> Merge after #3482 

**Motivation**

The `ethrex-replay::README.md` file was outdated.

**Description**

- Removes `ethrex_replay/README.md`.
- Creates `docs/ethrex_replay.md`.
- Adds some missing targets to `ethrex_replay/Makefile`.

Closes None

Author: avilagaston9

cmd/ethrex_replay/Makefile

@@ -6,16 +6,23 @@
 
 NETWORK ?= mainnet
 
+# Block parameters
 ifdef BLOCK_NUMBER
 REPLAY_BLOCK_ARGS = ${BLOCK_NUMBER}
 endif
 REPLAY_BLOCK_ARGS += --rpc-url ${RPC_URL} --network ${NETWORK} --bench
 
-ifdef BATCH_NUMBER
-REPLAY_BATCH_ARGS = ${BATCH_NUMBER}
+# Batch parameters
+REPLAY_BATCH_ARGS = ${BATCH_NUMBER} --rpc-url ${RPC_URL} --network ${NETWORK} --bench
+
+# Transaction parameters
+REPLAY_TX_ARGS = ${TX_HASH} --rpc-url ${RPC_URL} --network ${NETWORK}
+ifdef L2
+REPLAY_TX_ARGS += --l2
 endif
-REPLAY_BATCH_ARGS += --rpc-url ${RPC_URL} --network ${NETWORK} --bench
 
+# Block Composition parameters
+REPLAY_BLOCK_COMPOSITION_ARGS = ${START_BLOCK} ${END_BLOCK} --rpc-url ${RPC_URL} --network ${NETWORK}
 
 # Execution only
 ## Block
@@ -38,6 +45,14 @@ batch-risc0:
 batch-risc0-gpu:
 	cargo r -r --no-default-features --features "risc0,gpu,l2" -- execute batch ${REPLAY_BATCH_ARGS}
 
+## Transaction
+transaction:
+	cargo r -r -- execute transaction ${REPLAY_TX_ARGS}
+
+## Plot Composition
+plot:
+	cargo r -r -- block-composition ${REPLAY_BLOCK_COMPOSITION_ARGS}
+
 # Proving
 ## Block
 prove-sp1:
@@ -62,3 +77,6 @@ prove-batch-risc0:
 	cargo r -r --no-default-features --features "risc0,l2" -- prove batch ${REPLAY_BATCH_ARGS}
 prove-batch-risc0-gpu:
 	cargo r -r --no-default-features --features "risc0,gpu,l2" -- prove batch ${REPLAY_BATCH_ARGS}
+
+help:
+	cargo r -r -- --help

cmd/ethrex_replay/README.md

@@ -1,11 +1,3 @@
-# L1 block prover
+# ethrex-replay
 
-## Usage
-
-1. For now we only support SP1. Install their [toolchain](https://docs.succinct.xyz/docs/sp1/introduction) first (version 5.0.0).
-2. Run:
-   1. `make sp1 RPC_URL=<json rpc url> BLOCK_NUMBER=<number, optional>` for execution without proving
-   2. `make prove-sp1 RPC_URL=<json rpc url> BLOCK_NUMBER=<number, optional>` for generating a proof.
-   3. `make prove-sp1-gpu RPC_URL=<json rpc url> BLOCK_NUMBER=<number, optional>` for generating a proof with GPU acceleration.
-
-If `BLOCK_NUMBER` is not defined then the latest block will be selected.
+See full documentation [here](../../docs/ethrex_replay/ethrex_replay.md).

cmd/ethrex_replay/src/cli.rs

@@ -319,7 +319,7 @@ enum EthrexReplayCommand {
         about = "Proves blocks, ranges of blocks, or individual transactions."
     )]
     Prove(SubcommandProve),
-    #[command(about = "Proves blocks, ranges of blocks, or individual transactions.")]
+    #[command(about = "Plots the composition of a range of blocks.")]
     BlockComposition {
         #[arg(help = "Starting block. (Inclusive)")]
         start: usize,

docs/ethrex_replay/ethrex_replay.md

@@ -0,0 +1,128 @@
+# ethrex-replay
+
+A tool for executing and proving Ethereum blocks, transactions, and L2 batches — inspired by [starknet-replay](https://github.com/lambdaclass/starknet-replay).
+
+## Getting Started
+
+> **Note:** All commands must be run from the `ethrex/cmd/ethrex_replay` directory.
+
+### Dependencies
+
+#### [RISC0](https://dev.risczero.com/api/zkvm/install)
+
+```sh
+curl -L https://risczero.com/install | bash
+rzup install cargo-risczero 1.2.0
+```
+
+#### [SP1](https://docs.succinct.xyz/docs/sp1/introduction)
+
+```sh
+curl -L https://sp1up.succinct.xyz | bash
+sp1up --version 5.0.0
+```
+
+### Environment Variables
+
+Before running any command, set the following environment variables depending on the operation:
+
+```sh
+export RPC_URL=<RPC_URL>
+export BLOCK_NUMBER=<BLOCK_NUMBER>
+export BATCH_NUMBER=<BATCH_NUMBER>
+export TX_HASH=<TRANSACTION_HASH>
+export START_BLOCK=<START_BLOCK>
+export END_BLOCK=<END_BLOCK>
+export NETWORK=<mainnet|cancun|holesky|hoodi|sepolia|chainId>
+export L2=true
+```
+
+#### Variable Descriptions
+
+- `RPC_URL`: Ethereum JSON-RPC endpoint used to fetch on-chain data.
+- `BLOCK_NUMBER`: Block number to replay. If unset, the latest block will be used.
+- `BATCH_NUMBER`: L2 batch number to execute or prove.
+- `TX_HASH`: Hash of the transaction to replay.
+- `START_BLOCK` / `END_BLOCK`: Defines the block range to analyze and plot.
+- `NETWORK`: Logical network name or chain ID. Defaults to `mainnet`.
+- `L2`: Set to `true` to run transactions in L2 mode.
+
+> You only need to set the variables required by the command you're running.
+
+---
+
+## Running Examples
+
+### Execute a single block (no proving)
+
+Required: `RPC_URL`.
+Optionally: `BLOCK_NUMBER`, `NETWORK`
+
+```sh
+make sp1           # SP1 (CPU)
+make sp1-gpu       # SP1 (GPU)
+make risc0         # RISC0 (CPU)
+make risc0-gpu     # RISC0 (GPU)
+```
+
+### Prove a single block
+
+Required: `RPC_URL`.
+Optionally: `BLOCK_NUMBER`, `NETWORK`.
+
+```sh
+make prove-sp1
+make prove-sp1-gpu
+make prove-risc0
+make prove-risc0-gpu
+```
+
+### Execute an L2 batch (no proving)
+
+Required: `RPC_URL`, `BATCH_NUMBER`, `NETWORK`.
+
+```sh
+make batch-sp1
+make batch-sp1-gpu
+make batch-risc0
+make batch-risc0-gpu
+```
+
+### Prove an L2 batch
+
+Required: `RPC_URL`, `BATCH_NUMBER`, `NETWORK`.
+
+```sh
+make prove-batch-sp1
+make prove-batch-sp1-gpu
+make prove-batch-risc0
+make prove-batch-risc0-gpu
+```
+
+### Execute a transaction
+
+Required: `RPC_URL`, `TX_HASH`, `NETWORK`. 
+Optionally: `L2=true` (if the transaction is L2-specific)
+
+```sh
+make transaction
+```
+
+### Plot block composition
+
+Required: `RPC_URL`, `START_BLOCK`, `END_BLOCK`.
+Optionally: `NETWORK`
+
+```sh
+make plot
+```
+
+---
+
+## Check All Available Commands
+
+Run:
+
+```sh
+make help
+```