Customize Client Settings

By default, Ethshadow uses client CLI parameters that ensure that nodes discover each other and use the correct data directory and testnet settings. Furthermore, it automatically set some CLI parameters that are known to be required to make the clients work in Shadow simulations. The default parameters are listed in the client subpages. Also unless specified otherwise, Ethshadow uses the client executable found by the OS via the PATH environment variable.

Often, we want to use specific binaries or override CLI parameters. When trying to test different client configurations, we also may want to run multiple different binaries and configurations. In this page, we will show how to configure such setups.

Client configuration

In the ethereum subsection of your Ethshadow configuration, you can add a clients section to specify client settings. It is a mapping from a client ID to it's settings. You can choose your own client id, or use a default client ID to override the default settings. You can find a client type's default ID and default settings on its client subpage.

Every entry in the clients section has one mandatory parameter: type. Here you instruct Ethshadow what kind of client you want to use. Currently, this is unfortunately also necessary when overriding default client configs. Therefore, a most simple client configuration might look like this:

ethereum:
  clients:
    lighthouse:
      type: lighthouse

This overrides the default lighthouse client config, but doesn't mention any parameters to actually override, so in it's current form does not actually change anything. However, we can now easily add parameters to override. Some client types expose specific parameters to override (see the corresponding client subpage). There are also some parameters available with all client types, which we will explore in the next subsection.

Commonly available client parameters

• executable: Path to client binary to use. Absolute path is recommended. By default, the appropriately named binary in your PATH will be used.
• extra_args: Extra command line arguments to pass to the client after all arguments generated by Ethshadow. Empty by default.
• use_recommended_args: If false, Ethshadow will not use the arguments it deems recommended for this client type. See the client subpages for detailed lists of the recommended arguments. true by default.

Specifying clients in node configuration

After you have created your own client configuration in the clients section, you can now use the client ID in your node configuration section:

ethereum:
  nodes:
    - region: na_east
      reliability: reliable
      count:
        total: 1
    - region: europe
      reliability: reliable
      clients:
        el: reth
        cl: my_lighthouse
        vc: lighthouse_vc
      count:
        per_combination: 1
  clients:
    my_lighthouse:
      type: lighthouse
      extra_args: --awesome-cli-option

The node in na_east uses the default client stack (geth, lighthouse, lighthouse_vc), and the node in europe uses your my_lighthouse, along with reth. Note that you have to specify the full client stack if you want to use a non-default stack, i.e. while lighthouse_vc is the default, omitting it here would create a node without a validator client.

If you want to create multiple variants of a node, you can specify multiple client IDs within a single category. This works similar to specifying multiple regions or reliabilities. For example, changing line 11 above to cl: ["my_lighthouse", "lighthouse"] would create two nodes: one with the default lighthouse and one with your configuration. If you would also specify multiple EL clients (el: ["reth", "geth"]), we would get four nodes: one for every possible combination. Of course, you can modify the number of nodes per combination by adjusting the count property.

Note that the names of the "layers" of the client stack (el, cl, vc) are purely informational and do not influence config generation. You can freely add and remove layers as desired and name them as you like. This is useful for e.g. adding blob spammers, or having multiple or no VCs.

Default client stack

You can override the default client stack with the default_clients setting:

ethereum:
  #... snip ...
  default_clients:
    el: reth
    cl: my_lighthouse
    vc: lighthouse_vc

This will set the client stack for nodes where the stack is not explicitly defined. Note that you can only define a single client per layer here.