Skip to content

A Kurtosis package used by the Ethereum Foundation for testing the Merge

Notifications You must be signed in to change notification settings

barnabasbusa/eth2-package

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Ethereum Package

This is a Kurtosis Starlark Package that will:

  1. Generate EL & CL genesis information using this genesis generator
  2. Spin up a network of Eth2 Beacon/validator clients
  3. Add a transaction spammer that will repeatedly send transactions to the network
  4. Launch a consensus monitor instance attached to the network
  5. Optionally block until the Beacon nodes finalize an epoch (i.e. finalized_epoch > 0)

For much more detailed information about how the merge works in Ethereum testnets, see this document.

Quickstart

  1. Install Docker if you haven't done so already
  2. Install the Kurtosis CLI, or upgrade it to the latest version if it's already installed
  3. Ensure your Docker engine is running:
    docker image ls
  4. Run the package:
    kurtosis run --enclave eth2 github.com/kurtosis-tech/eth2-package

To remove the enclave running the Ethereum network, run kurtosis enclave rm -f eth2.

You can customize the package's behaviour by passing in a configuration JSON or YAML (see the "Configuration" section below). For example:

kurtosis run --enclave eth2 github.com/kurtosis-tech/eth2-package '{"global_client_log_level": "info"}'

For extra convenience, you can store the parameters in a file:

  1. Create a file in your home directory eth2-package-params.json with the following contents:

    global_client_log_level: "info"
  2. Run the package, passing in the params from the file:

    kurtosis run --enclave eth2 github.com/kurtosis-tech/eth2-package "$(cat ~/eth2-package-params.json)"

Management

Kurtosis will create a new enclave to house the services of the Ethereum network. This page contains documentation for managing the created enclave & viewing detailed information about it.

Configuration

To configure the package behaviour, you can modify your eth2-package-params.yaml file. The full YAML schema that can be passed in is as follows with the defaults provided:

Click to show all configuration options
{
    //  Specification of the participants in the network
    "participants": [
        {
            //  The type of EL client that should be started
            //  Valid values are "geth", "nethermind", "erigon" and "besu"
            "el_client_type": "geth",

            //  The Docker image that should be used for the EL client; leave blank to use the default for the client type
            //  Defaults by client:
            //  - geth: ethereum/client-go:latest
            //  - erigon: thorax/erigon:devel
            //  - nethermind: nethermind/nethermind:latest
            //  - besu: hyperledger/besu:develop            
            "el_client_image": "",

            //  The log level string that this participant's EL client should log at
            //  If this is emptystring then the global `logLevel` parameter's value will be translated into a string appropriate for the client (e.g. if
            //   global `logLevel` = `info` then Geth would receive `3`, Besu would receive `INFO`, etc.)
            //  If this is not emptystring, then this value will override the global `logLevel` setting to allow for fine-grained control
            //   over a specific participant's logging
            "el_client_log_level": "",

            //  A list of optional extra params that will be passed to the EL client container for modifying its behaviour
            "el_extra_params": [],

            //  The type of CL client that should be started
            //  Valid values are "nimbus", "lighthouse", "lodestar", "teku", and "prysm"
            "cl_client_type": "lighthouse",

            //  The Docker image that should be used for the EL client; leave blank to use the default for the client type
            //  Defaults by client (note that Prysm is different in that it requires two images - a Beacon and a validator - separated by a comma):
            //  - lighthouse: sigp/lighthouse:latest
            //  - teku: consensys/teku:latest
            //  - nimbus: statusim/nimbus-eth2:multiarch-latest
            //  - prysm: gcr.io/prysmaticlabs/prysm/beacon-chain:latest,gcr.io/prysmaticlabs/prysm/validator:latest
            //  - lodestar: chainsafe/lodestar:next
            "cl_client_image": "",

            //  The log level string that this participant's EL client should log at
            //  If this is emptystring then the global `logLevel` parameter's value will be translated into a string appropriate for the client (e.g. if
            //   global `logLevel` = `info` then Teku would receive `INFO`, Prysm would receive `info`, etc.)
            //  If this is not emptystring, then this value will override the global `logLevel` setting to allow for fine-grained control
            //   over a specific participant's logging
            "cl_client_log_level": "",

            //  A list of optional extra params that will be passed to the CL client Beacon container for modifying its behaviour
            //  If the client combines the Beacon & validator nodes (e.g. Teku, Nimbus), then this list will be passed to the combined Beacon-validator node
            "beacon_extra_params": [],

            //  A list of optional extra params that will be passed to the CL client validator container for modifying its behaviour
            //  If the client combines the Beacon & validator nodes (e.g. Teku, Nimbus), then this list will also be passed to the combined Beacon-validator node
            "validator_extra_params": [],

            // A set of parameters the node needs to reach an external block building network
            // If `null` then the builder infrastructure will not be instantiated
            // Example:
            // 
            // "relay_endpoints": [
            //   "https://[email protected]",
            //   "https://[email protected]",
            //   "https://[email protected]",
            //   "https://[email protected]"
            //  ]
            "builder_network_params": null
        }
    ],

    //  Configuration parameters for the Eth network
    "network_params": {
        //  The network ID of the Eth1 network
        "network_id": "3151908",

        //  The address of the staking contract address on the Eth1 chain
        "deposit_contract_address": "0x4242424242424242424242424242424242424242",

        //  Number of seconds per slot on the Beacon chain
        "seconds_per_slot": 12,

        //  Number of slots in an epoch on the Beacon chain
        "slots_per_epoch": 32,

        //  The number of validator keys that each CL validator node should get
        "num_validator_keys_per_node": 64,

        //  This mnemonic will a) be used to create keystores for all the types of validators that we have and b) be used to generate a CL genesis.ssz that has the children
        //   validator keys already preregistered as validators
        "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",

        //  The deneb for epoch -- arbitrarily large while we sort out https://github.com/kurtosis-tech/eth-network-package/issues/42 this will take 53~ hours for now
        "deneb_for_epoch": 500,

    },
    
    // True by defaults such that in addition to the Ethereum network:
    //  - A transaction spammer is launched to fake transactions sent to the network
    //  - Forkmon will be launched after CL genesis has happened
    //  - A prometheus will be started, coupled with grafana
    // If set to false:
    //  - only Ethereum network (EL and CL nodes) will be launched. Nothing else (no transaction spammer)
    //  - params for the CL nodes will be ignored (e.g. CL node image, CL node extra params)
    "launch_additional_services": true,

    //  If set, the package will block until a finalized epoch has occurred.
    //  If `waitForVerifications` is set to true, this extra wait will be skipped.
    "wait_for_finalization": false,

    //  If set to true, the package will block until all verifications have passed
    "wait_for_verifications": false,

    //  If set, after the merge, this will be the maximum number of epochs wait for the verifications to succeed.
    "verifications_epoch_limit": 5,

    //  The global log level that all clients should log at
    //  Valid values are "error", "warn", "info", "debug", and "trace"
    //  This value will be overridden by participant-specific values
    "global_client_log_level": "info",

    // Supports three valeus
    // Default: None - no mev boost, mev builder, mev flood or relays are spun up
    // mock - mock-builder & mev-boost are spun up
    // full - mev-boost, relays, flooder and builder are all spun up
    "mev_type": None
}

You can find the latest Kiln compatible docker images here: https://notes.ethereum.org/@launchpad/kiln

Developing On This Package

First, install prerequisites:

  1. Install Kurtosis itself

Then, run the dev loop:

  1. Make your code changes
  2. Rebuild and re-run the package by running the following from the root of the repo:
    kurtosis run . "{}"
    NOTE 1: You can change the value of the second positional argument flag to pass in extra configuration to the package per the "Configuration" section above! NOTE 2: The second positional argument accepts JSON.

To get detailed information about the structure of the package, visit the architecture docs.

When you're happy with your changes:

  • Add an entry to docs/changelog.md under the # TBD header describing your changes (this is required for CI checks to pass!)
  • Create a PR
  • Add one of the maintainers of the repo as a "Review Request":
    • parithosh (Ethereum)
    • gbouv (Kurtosis)
    • h4ck3rk3y (Kurtosis)
    • mieubrisse (Kurtosis)
  • Once everything works, merge!

Known Bugs

wait_for_epoch_finalization - doesn't work as expected, as Starlark doesn't have ways to do assertions on facts just yet. The issue tracks this.

About

A Kurtosis package used by the Ethereum Foundation for testing the Merge

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Starlark 100.0%