From e14b445c924b1a6510d8f4139dd7433356428a50 Mon Sep 17 00:00:00 2001 From: ltitanb Date: Mon, 16 Sep 2024 20:41:23 +0100 Subject: [PATCH] fix docs --- docs/docs/get_started/configuration.md | 6 ++- docs/docs/get_started/overview.md | 19 ++++--- docs/docs/get_started/running/binary.md | 5 +- docs/docs/get_started/running/docker.md | 8 +-- docs/docs/get_started/troubleshooting.md | 64 +++++++++++++++++++++++- 5 files changed, 82 insertions(+), 20 deletions(-) diff --git a/docs/docs/get_started/configuration.md b/docs/docs/get_started/configuration.md index cdab22a..63aa26d 100644 --- a/docs/docs/get_started/configuration.md +++ b/docs/docs/get_started/configuration.md @@ -4,7 +4,7 @@ description: Configure Commit-Boost # Configuration -After the Commit-Boost CLI and the modules are setup as detailed in the previous section, you will need to create a `cb-config.toml` file, detailing all the services that you want to run. +Commit-Boost needs a configuration file detailing all the services that you want to run. Create a `cb-config.toml` and adjust it depending on which modules you plan to run. For a full explanation of all the fields, check out [here](https://github.com/Commit-Boost/commit-boost-client/blob/main/config.example.toml). @@ -25,10 +25,12 @@ prometheus_config = "./docker/prometheus.yml" ``` You can find a list of MEV-Boost Holesky relays [here](https://www.coincashew.com/coins/overview-eth/mev-boost/mev-relay-list#holesky-testnet-relays). +After the sidecar is started, it will expose a port (`18550` in this example), that you need to point your CL to. This may be different depending on which CL you're running, check out [here](https://docs.flashbots.net/flashbots-mev-boost/getting-started/system-requirements#consensus-client-configuration-guides) for a list of configuration guides. + Note that in this setup, the signer module will not be started. ## Custom module -We currently provide a test module that needs to be built as a Docker image. To build the module run: +We currently provide a test module that needs to be built locally. To build the module run: ```bash bash scripts/build_local_modules.sh ``` diff --git a/docs/docs/get_started/overview.md b/docs/docs/get_started/overview.md index 403a7c5..be44b28 100644 --- a/docs/docs/get_started/overview.md +++ b/docs/docs/get_started/overview.md @@ -8,19 +8,18 @@ description: Initial setup Commit-Boost is currently in alpha development and **NOT** ready for production use. Please use caution ::: +Commit-Boost is primarily based on [Docker](https://www.docker.com/) to enable modularity, sandboxing and cross-platform compatibility. It is also possible to run Commit-Boost [natively](/get_started/running/binary) without Docker. -Commit-Boost currently uses [Docker](https://www.docker.com/) to enable modularity, sandboxing and cross-platform compatibility. We're also exploring [alternative](https://github.com/Commit-Boost/commit-boost-client/issues/18) approaches. - -In the current setup, each component roughly maps to a container: from a single `.toml` config file, the node operator can specify which modules they want to run, and Commit-Boost takes care of spinning up the services and creating links between them. +Each component roughly maps to a container: from a single `.toml` config file, the node operator can specify which modules they want to run, and Commit-Boost takes care of spinning up the services and creating links between them. Commit-Boost ships with two core modules: - a PBS module which implements implements the [BuilderAPI](https://ethereum.github.io/builder-specs/) for [MEV Boost](https://docs.flashbots.net/flashbots-mev-boost/architecture-overview/specifications) - a signer module, which implements the [Signer API](/api) and provides the interface for modules to request proposer commitments ## Setup -The Commit-Boost CLI creates a dynamic `docker-compose` file, with services and ports already set up. Alternatively, you can also run each module natively without using Docker. +The Commit-Boost CLI creates a dynamic `docker-compose` file, with services and ports already set up. -Either way, you can compile from source from our repo, or download binaries and fetch docker images from the official releases. +Whether you're using Docker or running the binaries natively, you can compile from source directly from the repo, or download binaries and fetch docker images from the official releases. ### Binaries and images Find the latest releases at https://github.com/Commit-Boost/commit-boost-client/releases. @@ -44,11 +43,11 @@ git checkout stable ``` :::note -If you get an `openssl` related error try running: `apt-get update && apt-get install -y openssl ca-certificates libssl3 libssl-dev` +If you get an `openssl` related error try running: `apt-get update && apt-get install -y openssl ca-certificates libssl3 libssl-dev build-essential pkg-config` ::: #### Docker -You can now build the CLI: +You will need to build the CLI to create the `docker-compose` file: ```bash # Build the CLI @@ -71,13 +70,13 @@ This will create two local images called `commitboost_pbs_default` and `commitbo #### Binaries -Alternatively, you can also build the modules from source and run them without Docker, in which case you wouldn't need the CLI: +Alternatively, you can also build the modules from source and run them without Docker, in which case you can skip the CLI and only compile the modules: ```bash -# Build the PBS module +# Build the PBS module, this corresponds to commit-boost-pbs in the releases cargo build --release --bin default-pbs -# Build the Signer module +# Build the Signer module, this corresponds to commit-boost-signer in the releases cargo build --release --bin signer-module ``` diff --git a/docs/docs/get_started/running/binary.md b/docs/docs/get_started/running/binary.md index 7ec6c2a..1268af0 100644 --- a/docs/docs/get_started/running/binary.md +++ b/docs/docs/get_started/running/binary.md @@ -3,7 +3,6 @@ description: Run Commit-Boost modules natively --- # Binary -It is also possible to run the native modules without using docker. :::warning Running the modules natively means you opt out of the security guarantees made by Docker and it's up to you how to setup and ensure the modules run safely @@ -13,7 +12,7 @@ Running the modules natively means you opt out of the security guarantees made b ## Setup Get the binary of the module either by compiling from source or by downloading a [published release](https://github.com/Commit-Boost/commit-boost-client/releases). -Modules need some environment variables to work correctly. Here is the complete list +Modules need some environment variables to work correctly. ### Common - `CB_CONFIG`: required, path to the `toml` config file @@ -45,7 +44,7 @@ Modules might also have additional envs required, which should be detailed by th ## Start -After creating the `cb-config.toml` file, you need to setup the required envs and run the binary. For example: +After creating the `cb-config.toml` file, setup the required envs and run the binary. For example: ```bash CB_CONFIG=./cb-config.toml commit-boost-pbs diff --git a/docs/docs/get_started/running/docker.md b/docs/docs/get_started/running/docker.md index e0dd28e..0d3f9b3 100644 --- a/docs/docs/get_started/running/docker.md +++ b/docs/docs/get_started/running/docker.md @@ -3,11 +3,11 @@ description: Run Commit-Boost with Docker --- # Docker -The `commit-boost` cli will generate a dynamic `docker-compose.yml` file using the provided `toml` config file. This is the recommended approach as Docker provides sandboxing of the containers from the rest of your system. +The Commit-Boost CLI will generate a dynamic `docker-compose.yml` file using the provided `toml` config file. This is the recommended approach as Docker provides sandboxing of the containers from the rest of your system. ## Init -After creating the `cb-config.toml` file, you can now run the Commit-Boost sidecar. First run: +First run: ```bash commit-boost init --config cb-config.toml ``` @@ -23,11 +23,11 @@ To start Commit-Boost run: commit-boost start --docker cb.docker-compose.yml [--env .cb.env] ``` -This will start up the services including PBS, commit modules (if any), and metrics collection (if enabled). +This will run `docker compose up` with the correct envs, and start up the services including PBS, commit modules (if any), and metrics collection (if enabled). The MEV-Boost server will be exposed at `pbs.port` from the config, `18550` in our example. You'll need to point your CL/Validator client to this port to be able to source blocks from the builder market. -If enabled, this will also start a Prometheus server on port `9090` and a Grafana instance on port `3000`. In Grafana, you will also find some preset dabhboards already connected. +If enabled, this will also start a Prometheus server on port `9090` and a Grafana instance on port `3000`. In Grafana, you will also find some preset dashboards already connected. ## Logs diff --git a/docs/docs/get_started/troubleshooting.md b/docs/docs/get_started/troubleshooting.md index 9d8b645..9788beb 100644 --- a/docs/docs/get_started/troubleshooting.md +++ b/docs/docs/get_started/troubleshooting.md @@ -3,4 +3,66 @@ description: Common issues --- # Troubleshooting -Commit-Boost is currently in alpha development so it's likely there are bugs, if you find any or have any question, please reach out on [Twitter](https://x.com/Commit_Boost) or [Telegram](https://t.me/+Pcs9bykxK3BiMzk5). \ No newline at end of file + +Commit-Boost is currently in alpha development so it's likely there are bugs, if you find any or have any question, please reach out on [Twitter](https://x.com/Commit_Boost) or [Telegram](https://t.me/+Pcs9bykxK3BiMzk5). + + +If you started the modules correctly you should see the following logs. + +## PBS +After the module started correctly you should see: +```bash +2024-09-16T19:27:16.004643Z INFO Starting PBS service address=0.0.0.0:18550 events_subs=0 +``` + +To check that the setup is correct and you are connected to relays, you can trigger manually the `/status` endpoint, by running: + +```bash +curl http://0.0.0.0:18550/eth/v1/builder/status -vvv + +* Trying 0.0.0.0:18550... +* Connected to 0.0.0.0 (127.0.0.1) port 18550 (#0) +> GET /eth/v1/builder/status HTTP/1.1 +> Host: 0.0.0.0:18550 +> User-Agent: curl/7.81.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-length: 0 +< date: Mon, 16 Sep 2024 19:32:07 GMT +< +* Connection #0 to host 0.0.0.0 left intact +``` + +if now you check the logs, you should see: + +```bash +2024-09-16T19:32:07.634966Z INFO status{req_id=62f1c0db-f277-49fa-91e7-a9a1c2b2a6d3}: ua="curl/7.81.0" relay_check=true +2024-09-16T19:32:07.642992Z INFO status{req_id=62f1c0db-f277-49fa-91e7-a9a1c2b2a6d3}: relay check successful +``` + +If the sidecar is setup correctly, it will receive and process calls from the CL: +#### Register validator +This should happen periodically, depending on your validator setup. + +```bash +2024-09-16T19:28:37.976534Z INFO register_validators{req_id=296f662f-0e7a-4f15-be75-55b8ca19ffc0}: ua="Lighthouse/v5.2.1-9e12c21" num_registrations=500 +2024-09-16T19:28:38.819591Z INFO register_validators{req_id=296f662f-0e7a-4f15-be75-55b8ca19ffc0}: register validator successful +``` + +#### Get header +This will only happen if some of your validators have a proposal slot coming up. + +```bash +2024-09-16T19:30:24.135376Z INFO get_header{req_id=74126c5f-69e6-4961-86a6-6c2597bf15f5 slot=2551052}: ua="Lighthouse/v5.2.1-9e12c21" parent_hash=0x641c99d6e4f14bf6d268eb2a8c0dc51c7030ab24e384c0e679f2a6b438d298ea validator_pubkey=0x84fc20b09496341f24abfcb6f407e916ecc317497c5b1bba4970e50e96cf5e731b88e51753064c30cb221453bd71aebf ms_into_slot=135 +2024-09-16T19:30:25.089477Z INFO get_header{req_id=74126c5f-69e6-4961-86a6-6c2597bf15f5 slot=2551052}: received header block_hash=0x0139686e8d251f010153875270256fce6f298d7b3f3f9129179fb86297dffad3 value_eth="0.001399518501462470" +``` + +#### Submit block +This will only happen if you received a header in the previous call, and if the header is higher than the locally built block. + +```bash +2024-09-16T14:38:01.409075Z INFO submit_blinded_block{req_id=6eb9a04d-6f79-4295-823f-c054582b3599 slot=2549590}: ua="Lighthouse/v5.2.1-9e12c21" slot_uuid=16186e06-0cd0-47bc-9758-daa1b66eff5c ms_into_slot=1409 block_hash=0xfa135ae6f2bfb32b0a47368f93d69e0a2b3f8b855d917ec61d78e78779edaae6 +2024-09-16T14:38:02.910974Z INFO submit_blinded_block{req_id=6eb9a04d-6f79-4295-823f-c054582b3599 slot=2549590}: received unblinded block +``` \ No newline at end of file