From 584507d1d36c129d6f5816bd25e64e7db18c1aa1 Mon Sep 17 00:00:00 2001 From: thedevbirb Date: Wed, 16 Oct 2024 10:26:23 +0200 Subject: [PATCH] docs(holesky): README launch wip update --- testnets/holesky/README2.md | 332 ++++++++++++++++++++++++++++++++++++ 1 file changed, 332 insertions(+) create mode 100644 testnets/holesky/README2.md diff --git a/testnets/holesky/README2.md b/testnets/holesky/README2.md new file mode 100644 index 00000000..c74761e8 --- /dev/null +++ b/testnets/holesky/README2.md @@ -0,0 +1,332 @@ +## Table of Contents + + + +* [Holesky Launch Instructions](#holesky-launch-instructions) + * [Prerequisites](#prerequisites) + * [Setup](#setup) + * [Standalone Binary](#standalone-binary) + * [Linux](#linux) + * [MacOS](#macos) + * [Configuration file](#configuration-file) + * [Docker](#docker) +* [Appendix](#appendix) + * [Command-line options](#command-line-options) + * [Delegations and signing options for standalone and docker container setup](#delegations-and-signing-options-for-standalone-and-docker-container-setup) + * [`bolt-delegations-cli`](#`bolt-delegations-cli`) + * [Using a private key directly](#using-a-private-key-directly) + + + +# Holesky Launch Instructions + +## Prerequisites + +In order to run Bolt you need some components already installed and running in +your system. + +**A synced Geth client:** + +At the moment Bolt is only compatible with the Geth execution client. Running +another execution client could lead to commitment faults because fallback block +building is not supported yet. You can download Geth here [the official +website](https://geth.ethereum.org/downloads). + +**A synced beacon node:** + +Bolt is compatible with every beacon client. Please refer to the various beacon +client implementations to download and run them. + +**Active validators:** + +The Bolt sidecar requires signing keys from active Ethereum validators, or +authorized delegates acting on their behalf, to issue and sign preconfirmations. + +> [!NOTE] +> To run the Bolt sidecar it may be necessary to restart your beacon client in +> order to set the sidecar as the [builder +> endpoint](https://ethereum.github.io/builder-specs/). + +## Setup + +There are various way to run the Bolt Sidecar depending on what infrastructure +you want to use and the way your preferred signing methods: + +- as a standalone binary; +- as a standalone Docker container; +- as a [Commit-Boost](https://commit-boost.github.io/commit-boost-client) + module (requires Docker). + +Running the Bolt sidecar as a standalone binary requires building it from +source. Both the standalone binary and the Docker container requires reading +signing keys from [ERC-2335](https://eips.ethereum.org/EIPS/eip-2335) keystores, +while the Commit-Boost module relies on an internal signer and a custom PBS +module instead of regular [MEV-Boost](https://boost.flashbots.net/). + +In this section we're going to explore each of these options and its +requirements. + +### Standalone Binary + +For running the Bolt Sidecar as a standalone binary you need to have the +following dependencies installed: + +- [git](https://git-scm.com/downloads); +- [Rust](https://www.rust-lang.org/tools/install). + +Depending on your platform you may need to install additional dependencies. + +#### Linux + +Debian-based distributions: + +```bash +sudo apt update && sudo apt install -y git build-essential libssl-dev build-essential ca-certificates +``` + +Fedora/Red Hat/CentOS distributions: + +```bash +sudo dnf groupinstall "Development Tools" && sudo dnf install -y git openssl-devel ca-certificates pkgconfig +``` + +Arch/Manjaro-based distributions: + +```bash +sudo pacman -Syu --needed base-devel git openssl ca-certificates pkgconf +``` + +Alpine Linux + +```bash +sudo apk add git build-base openssl-dev ca-certificates pkgconf +``` + +#### MacOS + +On MacOS after installing XCode Command Line tools (equivlanet to `build-essential` on Linux) you can install the other dependencies with [Homebew](https://brew.sh/): + +```zsh +xcode-select --install +brew install pkg-config openssl +``` + +--- + +After having installed the dependencies you can clone the Bolt repository by +running: + +```bash +git clone --branch v0.3.0 https://github.com/chainbound/bolt.git && cd bolt +``` + +Then you can build the Bolt sidecar by running: + +```bash +cargo build --release && mv target/release/bolt-sidecar . +``` + +In order to run correctly the sidecar you need to provide either a list command +line options or a configuration file. All the options available can be found by +running `./bolt-sidecar --help`, or you can find them in the [appendix](#command-line-options) of this +guide. + +#### Configuration file + +A configuration file can be either a `.env` file or a `.toml` file. If you use +`.env` file you can find a `.env.example` file in the repository that you can +use as a template. + +For a `.toml` file you can use the template in the `Config.example.toml`. Lastly +you need to specify the path of the configuration file by setting the +`BOLT_SIDECAR_CONFIG_PATH` environment variable to the path of the file. + +### Docker + +First, make sure to have both [Docker](https://docs.docker.com/engine/install/), +[Docker Compose](https://docs.docker.com/compose/install/) and +[git](https://git-scm.com/downloads) installed in your machine. + +Then clone the Bolt repository by running: + +```bash +git clone --branch v0.3.0 htts://github.com/chainbound/bolt.git && cd bolt +``` + +In order to launch the Bolt sidecar as a Docker container you need to create a +`.env` configuration file. For a reference template you can checkout the +`.env.example` file. + +# Appendix + +## Command-line options + +For completeness, here are all the command-line options available for the Bolt +sidecar. You can see them in your terminal by running the Bolt sidecar binary +with the `--help` flag: + +```text +Command-line options for the Bolt sidecar + +Usage: bolt-sidecar [OPTIONS] <--private-key |--commit-boost-address |--keystore-password > + +Options: + --port + Port to listen on for incoming JSON-RPC requests + + [env: BOLT_SIDECAR_PORT=] + [default: 8000] + + --execution-api-url + Execution client API URL + + [env: BOLT_SIDECAR_EXECUTION_API_URL=] + [default: http://localhost:8545] + + --beacon-api-url + URL for the beacon client + + [env: BOLT_SIDECAR_BEACON_API_URL=] + [default: http://localhost:5052] + + --engine-api-url + Execution client Engine API URL + + [env: BOLT_SIDECAR_ENGINE_API_URL=] + [default: http://localhost:8551] + + --constraints-url + URL for the Constraint sidecar client to use + + [env: BOLT_SIDECAR_CONSTRAINTS_URL=] + [default: http://localhost:3030] + + --constraints-proxy-port + Constraint proxy server port to use + + [env: BOLT_SIDECAR_CONSTRAINTS_PROXY_PORT=] + [default: 18551] + + --validator-indexes + Validator indexes of connected validators that the sidecar should accept commitments on behalf of. Accepted values: - a comma-separated list of indexes (e.g. "1,2,3,4") - a contiguous range of indexes (e.g. "1..4") - a mix of the + above (e.g. "1,2..4,6..8") + + [env: BOLT_SIDECAR_VALIDATOR_INDEXES=] + [default: ] + + --jwt-hex + The JWT secret token to authenticate calls to the engine API. + + It can either be a hex-encoded string or a file path to a file containing the hex-encoded secret. + + [env: BOLT_SIDECAR_JWT_HEX=] + [default: 0x7d5de8eaa5bf57c93710aa7423842cd1d6b06567fd99df4f7c62774cf86db169] + + --fee-recipient + The fee recipient address for fallback blocks + + [env: BOLT_SIDECAR_FEE_RECIPIENT=] + [default: 0x0000000000000000000000000000000000000000] + + --builder-private-key + Secret BLS key to sign fallback payloads with (If not provided, a random key will be used) + + [env: BOLT_SIDECAR_BUILDER_PRIVATE_KEY=] + [default: 0x643b385db30641c29abf6473f3fd7aca61196487a683a1796702cb38c6bb257b] + + --max-commitments-per-slot + Max number of commitments to accept per block + + [env: BOLT_SIDECAR_MAX_COMMITMENTS=] + [default: 128] + + --max-committed-gas-per-slot + Max committed gas per slot + + [env: BOLT_SIDECAR_MAX_COMMITTED_GAS=] + [default: 10000000] + + --min-priority-fee + Min priority fee to accept for a commitment + + [env: BOLT_SIDECAR_MIN_PRIORITY_FEE=] + [default: 1000000000] + + --chain + Chain on which the sidecar is running + + [env: BOLT_SIDECAR_CHAIN=] + [default: mainnet] + [possible values: mainnet, holesky, helder, kurtosis] + + --commitment-deadline + The deadline in the slot at which the sidecar will stop accepting new commitments for the next block (parsed as milliseconds) + + [env: BOLT_SIDECAR_COMMITMENT_DEADLINE=] + [default: 8000] + + --slot-time + The slot time duration in seconds. If provided, it overrides the default for the selected [Chain] + + [env: BOLT_SIDECAR_SLOT_TIME=] + [default: 12] + + --private-key + Private key to use for signing preconfirmation requests + + [env: BOLT_SIDECAR_PRIVATE_KEY=] + + --commit-boost-address + Socket address for the commit-boost sidecar + + [env: BOLT_SIDECAR_CB_SIGNER_URL=] + + --commit-boost-jwt-hex + JWT in hexadecimal format for authenticating with the commit-boost service + + [env: BOLT_SIDECAR_CB_JWT_HEX=] + + --keystore-password + The password for the ERC-2335 keystore. Reference: https://eips.ethereum.org/EIPS/eip-2335 + + [env: BOLT_SIDECAR_KEYSTORE_PASSWORD=] + + --keystore-path + Path to the keystores folder. If not provided, the default path is used + + [env: BOLT_SIDECAR_KEYSTORE_PATH=] + + --delegations-path + Path to the delegations file. If not provided, the default path is used + + [env: BOLT_SIDECAR_DELEGATIONS_PATH=] + +-m, --metrics-port +The port on which to expose Prometheus metrics + + [env: METRICS_PORT=] + [default: 3300] + +-d, --disable-metrics +[env: DISABLE_METRICS=] + +-h, --help +Print help (see a summary with '-h') +``` + +## Delegations and signing options for standalone and docker container setup + +As mentioned in the [prerequisites](#prerequisites) section, the Bolt sidecar +can sign commitments with a delegated set of private keys on behalf of active +Ethereum validators. This is the recommended way to run the Bolt sidecar as it +doesn't expose the active validator signing keys to any additional risk. + +In order to create these delegation you can use the `bolt-sidecar-cli` binary. + +### `bolt-delegations-cli` + +### Using a private key directly + +As you can see in the [command line options](#command-line-options) section you +can pass directly the private key to the Bolt sidecar using the `--private-key` +flag. This is the simplest setup and works