From 8c9b2465e33deaa3d3cf774ae16d6aa42bdd65d8 Mon Sep 17 00:00:00 2001 From: Suphanat Chunhapanya Date: Sun, 13 Oct 2024 22:46:56 +0700 Subject: [PATCH] Add docs --- .github/workflows/deploy.yml | 37 ---------- .github/workflows/mdbook.yml | 62 +++++++++++++++++ README.md | 93 +++++++++++++++++++++++++- docs/SUMMARY.md | 9 +++ docs/ethshadow.md | 3 + {guide/src => docs}/getting-started.md | 37 +++++----- {guide/src => docs}/installation.md | 10 +-- docs/supported-clients.md | 10 +++ ethshadow.rs | 0 mdbook/book.toml | 9 +++ 10 files changed, 206 insertions(+), 64 deletions(-) delete mode 100644 .github/workflows/deploy.yml create mode 100644 .github/workflows/mdbook.yml create mode 100644 docs/SUMMARY.md create mode 100644 docs/ethshadow.md rename {guide/src => docs}/getting-started.md (79%) rename {guide/src => docs}/installation.md (65%) create mode 100644 docs/supported-clients.md mode change 100755 => 100644 ethshadow.rs create mode 100644 mdbook/book.toml diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml deleted file mode 100644 index ded88cd..0000000 --- a/.github/workflows/deploy.yml +++ /dev/null @@ -1,37 +0,0 @@ -name: Deploy -on: - push: - branches: - - main - -jobs: - deploy: - runs-on: ubuntu-latest - permissions: - contents: write # To push a branch - pages: write # To push to a GitHub Pages site - id-token: write # To update the deployment status - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - name: Install latest mdbook - run: | - tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name') - url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz" - mkdir mdbook - curl -sSL $url | tar -xz --directory=./mdbook - echo `pwd`/mdbook >> $GITHUB_PATH - - name: Build Book - run: | - cd guide - mdbook build - - name: Setup Pages - uses: actions/configure-pages@v4 - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - path: 'guide/book' - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 diff --git a/.github/workflows/mdbook.yml b/.github/workflows/mdbook.yml new file mode 100644 index 0000000..764f3e0 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index d831fe2..283100f 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,94 @@ -# `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 + + +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. + + + +## 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: 10 min + # Display a progress indicator? + progress: true + +ethereum: + # Distribute this many validators evenly across all nodes + validators: 30 + # 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 +``` + +Check out `./data/shadow/hosts` which contais the stdout and stderr of every process (including geth and lighthouse) +of every node. + +## Supported clients + + + +✅ = 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 | ❔ | ❔ | ❔ | | + + + +## More Information + +See https://ppopth.github.io/ethshadow for the documentation diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..e4678a9 --- /dev/null +++ b/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]() diff --git a/docs/ethshadow.md b/docs/ethshadow.md new file mode 100644 index 0000000..de2086d --- /dev/null +++ b/docs/ethshadow.md @@ -0,0 +1,3 @@ +# The Shadow Simulator + +{{ #include ../README.md:overview }} diff --git a/guide/src/getting-started.md b/docs/getting-started.md similarity index 79% rename from guide/src/getting-started.md rename to docs/getting-started.md index 368b3a9..680c858 100644 --- a/guide/src/getting-started.md +++ b/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). \ No newline at end of file +Congrats! These are the basics of Ethshadow. diff --git a/guide/src/installation.md b/docs/installation.md similarity index 65% rename from guide/src/installation.md rename to docs/installation.md index c895af3..9490be4 100644 --- a/guide/src/installation.md +++ b/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. \ No newline at end of file +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 the [supported client page](supported-clients.md) for notes. diff --git a/docs/supported-clients.md b/docs/supported-clients.md new file mode 100644 index 0000000..b4c6621 --- /dev/null +++ b/docs/supported-clients.md @@ -0,0 +1,10 @@ +# Supported Clients + +{{ #include ../README.md:supported-clients }} + +## Other + +| Name | Status | Description | +|-------------------------------------|:------:|-----------------------------------------------------------------------------------------| +| Blobssss | ✅ | Simple blob transaction spammer designed for use in Ethshadow | +| Prometheus | ✅ | Used to capture metrics provided by the clients, currently only Lighthouse is supported | diff --git a/ethshadow.rs b/ethshadow.rs old mode 100755 new mode 100644 diff --git a/mdbook/book.toml b/mdbook/book.toml new file mode 100644 index 0000000..849e2d2 --- /dev/null +++ b/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"