docs: update readme configs & add more examples (#177)

This pull request adds the following: - [readme] verkle example configuration from: https://notes.ethereum.org/@parithosh/kurtosis-example - [readme] mock-mev example configuration from: https://notes.ethereum.org/@parithosh/kurtosis-example - [readme] Adds a paragraph about common debugging and management commands (logs, shell, export genesis files) - Adds an example network_params.json file with update images for mev-relay and mev-flood. This network_params.json file contains the default parameters
ethpandaops · Sep 3, 2023 · 4531252 · 4531252
1 parent 28adec1
commit 4531252
Show file tree

Hide file tree

Showing 2 changed files with 146 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Ethereum Package
 
-This is a [Kurtosis Package][starlark-docs] that will spin up a private Ethereum testnet over Docker or Kubernetes with multi-client support, Flashbot's `mev-boost` infrastructure for PBS-related testing/validation, and other useful network tools (transaction spammer, monitoring tools, etc). Kurtosis packages are entirely reproducible and composable.
+This is a [Kurtosis Package][starlark-docs] that will spin up a private Ethereum testnet over Docker or Kubernetes with multi-client support, Flashbot's `mev-boost` infrastructure for PBS-related testing/validation, and other useful network tools (transaction spammer, monitoring tools, etc). Kurtosis packages are entirely reproducible and composable, so this will work the same way over Docker or Kubernetes, in the cloud or locally on your machine.
 
 Specifically, this package will:
 1. Generate Execution Layer (EL) & Consensus Layer (CL) genesis information using [the Ethereum genesis generator](https://github.com/ethpandaops/ethereum-genesis-generator).
@@ -34,7 +34,7 @@ kurtosis run --enclave my-testnet github.com/kurtosis-tech/eth2-package "$(cat ~
 
 Where `network_params.json` contains the parameters for your network in your home directory.
 
-#### Run in Kubernetes
+#### Run on Kubernetes
 Kurtosis packages work the same way over Docker or on Kubernetes. Please visit our [Kubernetes docs](https://docs.kurtosis.com/k8s) to learn how to spin up a private testnet on a Kubernetes cluster. 
 
 #### Tear down
@@ -44,7 +44,29 @@ kurtosis enclave rm -f my-testnet
 ```
 
 ## Management
-To interact with the network and adjacent services, you should use the [Kurtosis CLI](https://docs.kurtosis.com/cli) which allows you to manage the enclave that houses your network.
+The [Kurtosis CLI](https://docs.kurtosis.com/cli) can be used to inspect and interact with the network. 
+
+For example, if you need shell access, simply run:
+```
+kurtosis service shell my-testnet $SERVICE_NAME
+```
+
+And if you need the logs for a service, simply run:
+```
+kurtosis service logs my-testnet $SERVICE_NAME
+```
+
+Check out the full list of CLI commands [here](https://docs.kurtosis.com/cli)
+
+## Debugging
+To grab the genesis files for the network, simply run:
+```
+kurtosis files download my-testnet $FILE_NAME $OUTPUT_DIRECTORY
+```
+For example, to retrieve the Execution Layer (EL) genesis data, run:
+```
+kurtosis files download my-testnet el-genesis-data ~/Downloads
+```
 
 ## Configuration
 To configure the package behaviour, you can modify your `network_params.json` file. The full JSON schema that can be passed in is as follows with the defaults provided:
@@ -147,7 +169,7 @@ To configure the package behaviour, you can modify your `network_params.json` fi
 
         // The epoch at which the capella and deneb forks are set to occur.
         "capella_fork_epoch": 2,
-        "deneb_fork_epoch": 4,
+        "deneb_fork_epoch": 4
     },
 
     // True by defaults such that in addition to the Ethereum network:
@@ -192,7 +214,7 @@ To configure the package behaviour, you can modify your `network_params.json` fi
     "mev_params": {
       // The image to use for MEV boot relay
       // This uses the h4ck3rk3y image instead of the flashbots image as that isn't published yet
-		"mev_relay_image": "h4ck3rk3y/mev-boost-relay",
+		"mev_relay_image": "flashbots/mev-boost-relay",
       // Extra parameters to send to the API
 		"mev_relay_api_extra_args": [],
       // Extra parameters to send to the housekeeper
@@ -212,6 +234,81 @@ To configure the package behaviour, you can modify your `network_params.json` fi
 
 #### Example configurations
 
+<details>
+    <summary>Verkle configuration example</summary>
+
+```json
+{
+  "participants": [
+    {
+      "el_client_type": "geth",
+      "el_client_image": "ethpandaops/geth:<VERKLE_IMAGE>",
+      "elExtraParams": ["--override.verkle=<UNIXTIMESTAMP>"],
+      "cl_client_type": "lighthouse",
+      "cl_client_image": "sigp/lighthouse:latest"
+    },
+    {
+      "el_client_type": "geth",
+      "el_client_image": "ethpandaops/geth:<VERKLE_IMAGE>",
+      "elExtraParams": ["--override.verkle=<UNIXTIMESTAMP>"],
+      "cl_client_type": "lighthouse",
+      "cl_client_image": "sigp/lighthouse:latest"
+    },
+    {
+      "el_client_type": "geth",
+      "el_client_image": "ethpandaops/geth:<VERKLE_IMAGE>",
+      "elExtraParams": ["--override.verkle=<UNIXTIMESTAMP>"],
+      "cl_client_type": "lighthouse",
+      "cl_client_image": "sigp/lighthouse:latest"
+    }
+  ],
+  "network_params": {
+    "capella_fork_epoch": 2,
+    "deneb_fork_epoch": 5
+  },
+  "launch_additional_services": false,
+  "wait_for_finalization": false,
+  "wait_for_verifications": false,
+  "global_client_log_level": "info"
+}
+```
+</details>
+
+<details>
+    <summary>A 3-node Ethereum network with "mock" MEV mode.</summary>
+    Useful for testing mev-boost and the client implimentations without adding the complexity of the relay. This can be enabled by a single config command and would deploy the [mock-builder](https://github.com/marioevz/mock-builder), instead of the relay infrastructure.
+
+```json
+{
+  "participants": [
+    {
+      "el_client_type": "geth",
+      "el_client_image": "",
+      "cl_client_type": "lighthouse",
+      "cl_client_image": "",
+      "count": 2
+    },
+    {
+      "el_client_type": "nethermind",
+      "el_client_image": "",
+      "cl_client_type": "teku",
+      "cl_client_image": "",
+      "count": 1
+    },
+    {
+      "el_client_type": "besu",
+      "el_client_image": "",
+      "cl_client_type": "prysm",
+      "cl_client_image": "",
+      "count": 2
+    },
+  ],
+  "mev_type": "mock",
+  "launch_additional_services": false
+}
+```
+</details>
+
 <details>
     <summary>A 5-node Ethereum network with three different CL and EL client combinations and mev-boost infrastructure in "full" mode.</summary>
 

diff --git a/network_params.json b/network_params.json
@@ -0,0 +1,44 @@
+{
+    "participants": [
+        {
+            "el_client_type": "geth",
+            "el_client_image": "ethereum/client-go:latest",
+            "el_client_log_level": "",
+            "el_extra_params": [],
+            "cl_client_type": "lighthouse",
+            "cl_client_image": "sigp/lighthouse:latest",
+            "cl_client_log_level": "",
+            "beacon_extra_params": [],
+            "validator_extra_params": [],
+            "builder_network_params": null,
+            "count": 1
+        }
+    ],
+    "network_params": {
+        "network_id": "3151908",
+        "deposit_contract_address": "0x4242424242424242424242424242424242424242",
+        "seconds_per_slot": 12,
+        "slots_per_epoch": 32,
+        "num_validator_keys_per_node": 64,
+        "preregistered_validator_keys_mnemonic": "giant issue aisle success illegal bike spike question tent bar rely arctic volcano long crawl hungry vocal artwork sniff fantasy very lucky have athlete",
+        "capella_fork_epoch": 2,
+        "deneb_fork_epoch": 4
+    },
+    "launch_additional_services": true,
+    "wait_for_finalization": false,
+    "wait_for_verifications": false,
+    "verifications_epoch_limit": 5,
+    "global_client_log_level": "info",
+    "snooper_enabled": false,
+    "parallel_keystore_generation": false,
+    "mev_type": "None",
+    "mev_params": {
+		"mev_relay_image": "flashbots/mev-boost-relay",
+		"mev_relay_api_extra_args": [],
+		"mev_relay_housekeeper_extra_args": [],
+		"mev_relay_website_extra_args": [],
+		"mev_builder_extra_args": [],
+		"mev_flood_image": "flashbots/mev-flood",
+		"mev_flood_extra_args": []
+    }
+}