Add docs

.github/workflows/mdbook.yml

@@ -0,0 +1,62 @@
+# Sample workflow for building and deploying a mdBook site to GitHub Pages
+#
+# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
+#
+name: Deploy mdBook site to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    env:
+      MDBOOK_VERSION: 0.4.36
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install mdBook
+        run: |
+          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
+          rustup update
+          cargo install --version ${MDBOOK_VERSION} mdbook
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Build with mdBook
+        run: |
+          cd mdbook
+          mdbook build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./mdbook/book
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -1,7 +1,88 @@
-# `ethshadow`: Discrete-event Ethereum network simulations
+# Ethshadow: Discrete-event Ethereum network simulations
 
-`ethshadow` is a tool to easily configure and run simulated Ethereum networks. Under the hood, it uses
+<!--- ANCHOR: overview (for mdbook) -->
+
+Ethshadow is a tool to easily configure and run simulated Ethereum networks. Under the hood, it uses
 [Shadow](https://shadow.github.io/), a discrete-event network simulator that enables us to run simulations with actual
 Ethereum clients instead of specifically written simulation code.
 
-Check out the [guide](https://ethereum.github.io/ethshadow) to get started!
+The advantages of using Ethshadow are as follows.
+
+1. It already includes everything in the simulation (e.g. libp2p, discv5, etc).
+2. It uses the same software as the mainnet and the public testnets.
+3. If there is any upgades in lighthouse, we can integrate those upgrades easily in the simulation.
+
+If you want to simulate a new Ethereum protocol, what you need to do is just to implement it in lighthouse or geth or
+any other supported EL and CL clients and run it using this simulator.
+
+<!--- ANCHOR_END: overview (for mdbook) -->
+
+## Quickstart
+
+Install Ethshadow.
+```
+cargo install --path .
+```
+
+Save the following file to a config file `myfirstsim.yaml`.
+
+```yaml
+general:
+  # How much time should we simulate?
+  stop_time: 20min
+  # Display a progress indicator?
+  progress: true
+
+ethereum:
+  # Distribute this many validators evenly across all nodes
+  validators: 50
+  # Create this many nodes with Geth, Lighthouse and a Validator client.
+  # Additionally, a host with one boot node for CL and EL each is added.
+  nodes: 10
+```
+
+Run the simulation.
+```shell
+ethshadow myfirstsim.yaml
+```
+
+## Supported clients
+
+<!--- ANCHOR: supported-clients (for mdbook) -->
+
+✅ = Available, works out-of-the-box with latest release
+🚧 = Available, works with modifications (see subpage for details)
+❌ = Unavailable, does not currently work
+❔ = Unavailable, not yet tested
+
+A client is considered to work if it can follow the chain and perform the necessary duties for validating. Other
+features might not work.
+
+## Execution Layer
+
+| Name                    | Node | Boot Node | Latest tested version |
+|-------------------------|:----:|:---------:|:---------------------:|
+| Besu                    |  ❔   |     ❔     |                       |
+| Erigon                  |  ❔   |     ❔     |                       |
+| EthereumJS              |  ❔   |     ❔     |                       |
+| [Geth](clients/geth.md) |  ✅   |     ✅     | v1.14.11              |
+| Nethermind              |  ❔   |     ❔     |                       |
+| [Reth](clients/reth.md) |  🚧  |     ❔     |                       |
+
+
+## Consensus Layer
+
+| Name                                | Node | Boot Node | Validator Client | Latest tested version |
+|-------------------------------------|:----:|:---------:|:----------------:|:---------------------:|
+| Grandine                            |  ❔   |     ❔     |        ❔         |                       |
+| [Lighthouse](clients/lighthouse.md) |  ✅   |     ✅     |        ✅         | v5.3.0                |
+| Lodestar                            |  ❔   |     ❔     |        ❔         |                       |
+| Nimbus                              |  ❔   |     ❔     |        ❔         |                       |
+| Prysm                               |  ❔   |     ❔     |        ❔         |                       |
+| Teku                                |  ❔   |     ❔     |        ❔         |                       |
+
+<!--- ANCHOR_END: supported-clients (for mdbook) -->
+
+## More Information
+
+See https://ethereum.github.io/ethshadow for the documentation

docs/SUMMARY.md

@@ -0,0 +1,9 @@
+# The Ethshadow Documentation
+
+[The Ethshadow Simulator](ethshadow.md)
+
+- [Installation](installation.md)
+- [Supported Clients](supported-clients.md)
+- [Getting Started](getting-started.md)
+- [Advanced Usage]()
+- [Limitations]()

docs/ethshadow.md

@@ -0,0 +1,3 @@
+# The Shadow Simulator
+
+{{ #include ../README.md:overview }}

guide/src/getting-started.md → docs/getting-started.md

@@ -1,9 +1,9 @@
 # Getting Started
 
-First, [install `ethshadow` and its dependencies](installation.md). Also, make sure `lighthouse`, `lcli`, `geth`, and 
+First, [install Ethshadow and its dependencies](installation.md). Also, make sure `lighthouse`, `lcli`, `geth`, and
 `bootnode` are available in your PATH environment variable. (TODO explain how to specify executable paths instead?)
 
-`ethshadow` uses, like Shadow, a yaml configuration file. Create a new File, e.g. `myfirstsim.yaml`.
+Ethshadow uses, like Shadow, a yaml configuration file. Create a new File, e.g. `myfirstsim.yaml`.
 
 In this file, you can specify any configuration option Shadow itself supports. There are [many options](https://shadow.github.io/docs/guide/shadow_config_spec.html),
 we will focus on the essentials here. Add the following to your configuration:
@@ -16,8 +16,8 @@ general:
   progress: true
 ```
 
-These values will be passed to Shadow. Usually, when using Shadow directly, we would now specify our network topology 
-and hosts to simulate. However, `ethshadow` does that for us. `ethshadow` introduces several new configuration options,
+These values will be passed to Shadow. Usually, when using Shadow directly, we would now specify our network topology
+and hosts to simulate. However, Ethshadow does that for us. Ethshadow introduces several new configuration options,
 contained in the `ethereum` section. In its most simple form, it looks like this:
 
 ```yaml
@@ -29,25 +29,25 @@ ethereum:
   nodes: 10
 ```
 
-That's it! After adding that, our simulation is ready to run. In a shall, move to the directory your config is in and 
+That's it! After adding that, our simulation is ready to run. In a shall, move to the directory your config is in and
 invoke:
 
 ```shell
 ethshadow myfirstsim.yaml
 ```
 
-The first run might take a moment, as Docker will have to pull an image. After some time, `Startin Shadow 3.2.0` will 
+The first run might take a moment, as Docker will have to pull an image. After some time, `Startin Shadow 3.2.0` will
 be logged, and the simulation will begin. Notice how the Simulation will run at variable speed: it will likely hang
 for a moment at `00:00:04.999`, because all nodes start after giving the boot node five seconds to prepare. As genesis o
-ccurs at `00:05:00.000`, time will pass relatively quickly until then, as nodes only search for peers and wait for 
+ccurs at `00:05:00.000`, time will pass relatively quickly until then, as nodes only search for peers and wait for
 genesis. At approximately `00:05:12.000`, simulation will take a bit, as the first block is built and all nodes verify
 it.
 
 While waiting for the simulation to finish, note that a `data` directory was created next to your configuration file.
-Feel free to look around in it. For each node, the clients' data directories are included. You can observe the 
+Feel free to look around in it. For each node, the clients' data directories are included. You can observe the
 simulation by opening client logs contained within and following as the log gets written. As these logs tend to be
-a bit noisy, you might also want to check the `shadow` subdirectory, which contains files where the stdout and stderr 
-of each process is redirected to. Here, you can easily check whether the simulation works by checking for error 
+a bit noisy, you might also want to check the `shadow` subdirectory, which contains files where the stdout and stderr
+of each process is redirected to. Here, you can easily check whether the simulation works by checking for error
 messages and skipped slots.
 
 Feel free to let the simulation finish or cancel it with Ctrl-C.
@@ -80,19 +80,19 @@ ethereum:
 ```
 
 As you can see, we replaced the simple node count with a list of node specifications. Here, the yaml list has tow
-items. 
+items.
 
 In the first one, we define a host located in europe, with a reliable internet connection. We also specify that
-a Geth bootnode and a Lighthouse bootnode shall be run on that node. 
+a Geth bootnode and a Lighthouse bootnode shall be run on that node.
 
-In the second  one, we actually specify multimple nodes: notice the `count` property, which specifies five nodes per 
-combination. Combination here means every possible pair of specified locations and reliabilities: `europe` with 
+In the second  one, we actually specify multimple nodes: notice the `count` property, which specifies five nodes per
+combination. Combination here means every possible pair of specified locations and reliabilities: `europe` with
 `reliable`, `europe` with `home`, `na_east` with `reliable`, and so on. As there are `2 * 3 = 6` combinations,
 a total of `5 * 6 = 30` nodes will be created. As we specified 60 validators, each node will host 2 validators.
 
 But what is a "location" and a "reliability"? In Ethereum, we have a lot of globally distributed nodes. Therefore,
-we want to be able to simulate with varying latency between nodes. There are 8 built-in regions: `australia`, 
-`east_asia`, `europe`, `na_east`, `na_west`, `south_america`, `south_aftica`, and `west_asia`. `ethshadow` has a table
+we want to be able to simulate with varying latency between nodes. There are 8 built-in regions: `australia`,
+`east_asia`, `europe`, `na_east`, `na_west`, `south_america`, `south_aftica`, and `west_asia`. Ethshadow has a table
 with estimated latencies between these regions and will generate a network topology to make Shadow apply these
 latencies to the traffic between the nodes.
 
@@ -107,7 +107,7 @@ Ethereum, we want to include them into our simulations. The following reliabilit
 | constrained | 5 Mbit/s                | 20ms          | 0.1%              |
 | bad         | 2 Mbit/s                | 500ms         | 20%               |
 
-You can define your own locations and reliabilities as well as override the default values of the existing ones. TODO link
+You can define your own locations and reliabilities as well as override the default values of the existing ones.
 
 Before we can start a simulation with our more sophisticated simulation, we have to either delete the `data` directory
 from the previous run or specify another directory:
@@ -116,5 +116,4 @@ from the previous run or specify another directory:
 ethshadow -d data_sophisticated sophisticated.yaml
 ```
 
-Congrats! These are the basics of `ethshadow`. Next we are going to look at more advanced usage. Also check out
-the [Configuration Reference](configuration-reference.md).
+Congrats! These are the basics of Ethshadow.

guide/src/installation.md → docs/installation.md

@@ -1,10 +1,10 @@
 # Installation
 
-Only Linux is supported. For more details, see the 
+Only Linux is supported. For more details, see the
 [Shadow documentation](https://shadow.github.io/docs/guide/supported_platforms.html).
 
 1. [Install Shadow and its dependencies](https://shadow.github.io/docs/guide/install_dependencies.html). Shadow should be available in your PATH environment variable.
-2. [Install Docker](https://docs.docker.com/engine/install/) and [make sure your user is allowed to manage Docker](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). 
-The Docker daemon must be running while `ethshadow` prepares the simulation.
-3. Install `ethshadow` by running `cargo install --path .`
-4. Ensure that all clients you want to use in the simulation are installed, see each client's page for notes.
+2. [Install Docker](https://docs.docker.com/engine/install/) and [make sure your user is allowed to manage Docker](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user).
+The Docker daemon must be running while Ethshadow prepares the simulation.
+3. Install Ethshadow by running `cargo install --path .`
+4. Ensure that all clients you want to use in the simulation are installed, see each client's page for notes.

docs/supported-clients.md

@@ -0,0 +1,10 @@
+# Supported Clients
+
+{{ #include ../README.md:supported-clients }}
+
+## Other
+
+| Name                                | Status | Description                                                                             |
+|-------------------------------------|:------:|-----------------------------------------------------------------------------------------|
+| [Blobssss](clients/blobssss.md)     |   ✅    | Simple blob transaction spammer designed for use in `ethshadow`                         |
+| [Prometheus](clients/prometheus.md) |   ✅    | Used to capture metrics provided by the clients, currently only Lighthouse is supported |

mdbook/book.toml

@@ -0,0 +1,9 @@
+[book]
+title = "The Ethshadow Documentation"
+authors = ["Daniel Knopik", "Pop Chunhapanya"]
+language = "en"
+multilingual = false
+src = "../docs"
+
+[output.html]
+git-repository-url = "https://github.com/ppopth/ethereum"