diff --git a/docs/docs/developing/custom-modules.md b/docs/docs/developing/custom-modules.md index a15ce514..7282db70 100644 --- a/docs/docs/developing/custom-modules.md +++ b/docs/docs/developing/custom-modules.md @@ -2,10 +2,10 @@ sidebar_position: 1 --- # Custom Modules -Commit-Boost aims to provide an open platform for developers to create and distribute commitment protocols sidecars. +Commit-Boost aims to provide an open platform for developers to create and distribute commitment protocols sidecars. There are three ways to leverage Commit-Boost modularity: -1. Commit Modules, which request signatures from the proposer, e.g. for preconfirmations ([example](https://github.com/Commit-Boost/commit-boost-client/tree/78bdc47bf89082f4d1ea302f9a3f86f609966b28/examples/da_commit)) -2. PBS Modules, which tweak the default PBS Module with additional logic, e.g. verifying additional constraints in `get_header` ([example](https://github.com/Commit-Boost/commit-boost-client/tree/78bdc47bf89082f4d1ea302f9a3f86f609966b28/examples/status_api)) -3. PBS Events, which trigger based on the different events of the PBS lifecycle and can be used e.g. for monitoring and reporting ([example](https://github.com/Commit-Boost/commit-boost-client/tree/78bdc47bf89082f4d1ea302f9a3f86f609966b28/examples/builder_log)) +1. Commit Modules, which request signatures from the proposer, e.g. for preconfirmations ([example](https://github.com/Commit-Boost/commit-boost-client/tree/78bdc47bf89082f4d1ea302f9a3f86f609966b28/examples/da_commit)). +2. PBS Modules, which tweak the default PBS Module with additional logic, e.g. verifying additional constraints in `get_header` ([example](https://github.com/Commit-Boost/commit-boost-client/tree/78bdc47bf89082f4d1ea302f9a3f86f609966b28/examples/status_api)). +3. PBS Events, which trigger based on the different events of the PBS lifecycle and can be used e.g. for monitoring and reporting ([example](https://github.com/Commit-Boost/commit-boost-client/tree/78bdc47bf89082f4d1ea302f9a3f86f609966b28/examples/builder_log)). diff --git a/docs/docs/get_started/configuration.md b/docs/docs/get_started/configuration.md index 638c7859..182bc870 100644 --- a/docs/docs/get_started/configuration.md +++ b/docs/docs/get_started/configuration.md @@ -4,11 +4,10 @@ description: Configure Commit-Boost # Configuration -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. +Commit-Boost needs a configuration file detailing all the services that you want to run. Create a `cb-config.toml` and modify 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). - -For some additional examples on config presets, check out [here](https://github.com/Commit-Boost/commit-boost-client/tree/main/configs). +- For a full explanation of all the fields, check out [here](https://github.com/Commit-Boost/commit-boost-client/blob/main/config.example.toml). +- For some additional examples on config presets, check out [here](https://github.com/Commit-Boost/commit-boost-client/tree/main/configs). ## Minimal PBS setup on Holesky ```toml @@ -27,7 +26,9 @@ 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. +:::note +In this setup, the signer module will not be started. +::: ## Signer module @@ -131,6 +132,7 @@ We currently support Lighthouse, Prysm, Teku and Lodestar's keystores so it's ea #### Config: ```toml + [signer] [signer.local.loader] format = "lodestar" keys_path = "keys" @@ -188,7 +190,7 @@ To persist proxy keys across restarts, you must enable the proxy store in the co
ERC2335 - The keys are stored in a ERC-2335 style keystore, among with a password. This way, you can safely share the keys directory so without the password they are useless. + The keys are stored in a ERC-2335 style keystore, along with a password. This way, you can safely share the keys directory as without the password they are useless. #### File structure @@ -279,7 +281,7 @@ A few things to note: To learn more about developing modules, check out [here](/category/developing). ## Vouch -[Vouch](https://github.com/attestantio/vouch) is a multi-node validator client built by [Attestant](https://www.attestant.io/). Vouch is particular in that it also integrates a MEV-Boost client to interact with relays. The Commit-Boost PBS module is compatible with the Vouch `blockrelay` since it implements the Builder-API, just like relays do. For example, depending on your setup and preference, you may want to fetch headers from a given relay using Commit-Boost vs using the built-in Vouch `blockrelay`. +[Vouch](https://github.com/attestantio/vouch) is a multi-node validator client built by [Attestant](https://www.attestant.io/). Vouch is particular in that it also integrates an MEV-Boost client to interact with relays. The Commit-Boost PBS module is compatible with the Vouch `blockrelay` since it implements the same Builder-API as relays. For example, depending on your setup and preference, you may want to fetch headers from a given relay using Commit-Boost vs using the built-in Vouch `blockrelay`. ### Configuration Get familiar on how to set up Vouch [here](https://github.com/attestantio/vouch/blob/master/docs/getting_started.md). @@ -302,7 +304,9 @@ In this setup, the BN Builder-API endpoint will be pointing to the PBS module (e This will bypass the `blockrelay` entirely so make sure all relays are properly configured in the `[[relays]]` section. -**Note**: this approach could also work if you have a multi-beacon-node setup, where some BNs fetch directly via Commit-Boost while others go through the `blockrelay`. +:::note +This approach could also work if you have a multi-beacon-node setup, where some BNs fetch directly via Commit-Boost while others go through the `blockrelay`. +::: ### Notes - It's up to you to decide which relays will be connected via Commit-Boost (`[[relays]]` section in the `toml` config) and which via Vouch (additional entries in the `relays` field). Remember that any rate-limit will be shared across the two sidecars, if running on the same machine. diff --git a/docs/docs/get_started/overview.md b/docs/docs/get_started/overview.md index cbf07772..8247c84e 100644 --- a/docs/docs/get_started/overview.md +++ b/docs/docs/get_started/overview.md @@ -8,8 +8,8 @@ Commit-Boost is primarily based on [Docker](https://www.docker.com/) to enable m 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 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 +- A PBS module which 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 @@ -17,17 +17,17 @@ The Commit-Boost CLI creates a dynamic `docker-compose` file, with services and 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 +## Binaries and images Find the latest releases at https://github.com/Commit-Boost/commit-boost-client/releases. The modules are also published at [each release](https://github.com/orgs/Commit-Boost/packages?repo_name=commit-boost-client). ### From source -Requirements: +Requirements: - Rust 1.80 :::note -run `rustup update` to update Rust and Cargo to the latest version +Run `rustup update` to update Rust and Cargo to the latest version ::: ```bash @@ -42,7 +42,7 @@ git checkout stable 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 +### Docker You will need to build the CLI to create the `docker-compose` file: ```bash @@ -53,7 +53,7 @@ cargo build --release --bin commit-boost-cli ./target/release/commit-boost-cli --version ``` -and the modules as Docker images +and the modules as Docker images: ```bash bash scripts/build_local_images.sh ``` @@ -64,7 +64,7 @@ If you require `sudo` access to run Docker, you will need `sudo` to run some of This will create two local images called `commitboost_pbs_default` and `commitboost_signer` for the Pbs and Signer module respectively. Make sure to use these images in the `docker_image` field in the `[pbs]` and `[signer]` sections of the `.toml` config file, respectively. -#### Binaries +### Binaries 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: diff --git a/docs/docs/get_started/running/binary.md b/docs/docs/get_started/running/binary.md index 2c93d3f2..a20623ba 100644 --- a/docs/docs/get_started/running/binary.md +++ b/docs/docs/get_started/running/binary.md @@ -5,7 +5,7 @@ description: Run Commit-Boost modules natively # Binary :::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 +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. ::: @@ -15,35 +15,34 @@ Get the binary of the module either by compiling from source or by downloading a Modules need some environment variables to work correctly. ### Common -- `CB_CONFIG`: required, path to the `toml` config file -- `CHAIN_SPEC_ENV`: optional, path to a chain spec file. This will override the `[chain]` field in the `toml` config -- `CB_METRICS_PORT`: optional, port where to expose the `/metrics` endpoint for Prometheus -- `CB_LOGS_DIR`: optional, directory to store logs. This will override the directory in the `toml` config +- `CB_CONFIG`: required, path to the `.toml` config file. +- `CHAIN_SPEC_ENV`: optional, path to a chain spec file. This will override the `[chain]` field in the `.toml` config. +- `CB_METRICS_PORT`: optional, port where to expose the `/metrics` endpoint for Prometheus. +- `CB_LOGS_DIR`: optional, directory to store logs. This will override the directory in the `.toml` config. ### PBS Module -- `CB_BUILDER_URLS`: optional, comma-separated list of urls to `events` modules where to post builder events -- `CB_PBS_ENDPOINT`: optional, override the endpoint where the PBS module will open the port for the beacon node -- `CB_MUX_PATH_{ID}`: optional, override where to load mux validator keys for mux with id=\{ID\} -### Signer Module -- `CB_JWTS`: required, comma-separated list of `MODULE_ID=JWT` to process signature requests -- `CB_SIGNER_PORT`: required, port to open the signer server on -For loading keys we currently support: - - `CB_SIGNER_LOADER_FILE`: path to a `.json` with plaintext keys (for testing purposes only) - - `CB_SIGNER_LOADER_FORMAT`, `CB_SIGNER_LOADER_KEYS_DIR` and `CB_SIGNER_LOADER_SECRETS_DIR`: paths to the `keys` and `secrets` directories or files (ERC-2335 style keystores, see [Signer config](../configuration/#signer-module) for more info) -For storing proxy keys we currently support: - - `CB_PROXY_STORE_DIR`: directory where proxy keys and delegations will be saved in plaintext (for testing purposes only) - - `CB_PROXY_KEYS_DIR` and `CB_PROXY_SECRETS_DIR`: paths to the `keys` and `secrets` directories (ERC-2335 style keystores, see [Signer config](../configuration#proxy-keys-store) for more info) +- `CB_BUILDER_URLS`: optional, comma-separated list of urls to `events` modules where to post builder events. +- `CB_PBS_ENDPOINT`: optional, override the endpoint where the PBS module will open the port for the beacon node. +- `CB_MUX_PATH_{ID}`: optional, override where to load mux validator keys for mux with `id=\{ID\}`. +### Signer Module +- `CB_JWTS`: required, comma-separated list of `MODULE_ID=JWT` to process signature requests. +- `CB_SIGNER_PORT`: required, port to open the signer server on. +- For loading keys we currently support: + - `CB_SIGNER_LOADER_FILE`: path to a `.json` with plaintext keys (for testing purposes only). + - `CB_SIGNER_LOADER_FORMAT`, `CB_SIGNER_LOADER_KEYS_DIR` and `CB_SIGNER_LOADER_SECRETS_DIR`: paths to the `keys` and `secrets` directories or files (ERC-2335 style keystores, see [Signer config](../configuration/#signer-module) for more info). +- For storing proxy keys we currently support: + - `CB_PROXY_STORE_DIR`: directory where proxy keys and delegations will be saved in plaintext (for testing purposes only). ### Modules -- `CB_MODULE_ID`: required, unique id of the module +- `CB_MODULE_ID`: required, unique id of the module. #### Commit modules -- `CB_SIGNER_URL`: required, url to the signer module server -- `CB_SIGNER_JWT`: required, jwt to use to for signature requests (needs to match what is in `CB_JWTS`) +- `CB_SIGNER_URL`: required, url to the signer module server. +- `CB_SIGNER_JWT`: required, jwt to use to for signature requests (needs to match what is in `CB_JWTS`). #### Events modules -- `CB_BUILDER_PORT`: required, port to open to receive builder events from the PBS module +- `CB_BUILDER_PORT`: required, port to open to receive builder events from the PBS module. Modules might also have additional envs required, which should be detailed by the maintainers. diff --git a/docs/docs/get_started/running/docker.md b/docs/docs/get_started/running/docker.md index 3dd1473d..6646c196 100644 --- a/docs/docs/get_started/running/docker.md +++ b/docs/docs/get_started/running/docker.md @@ -3,7 +3,7 @@ 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 @@ -12,9 +12,9 @@ First run: commit-boost-cli init --config cb-config.toml ``` This will create up to three files: -- `cb.docker-compose.yml`, which contains the full setup of the Commit-Boost services -- `.cb.env`, with local env variables, including JWTs for modules, only created if the signer module is enabled -- `target.json`, which enables dynamic discovery of services for metrics scraping via Prometheus, only created if metrics are enabled +- `cb.docker-compose.yml` which contains the full setup of the Commit-Boost services. +- `.cb.env` with local env variables, including JWTs for modules, only created if the signer module is enabled. +- `target.json` which enables dynamic discovery of services for metrics scraping via Prometheus, only created if metrics are enabled. ## Start diff --git a/docs/docs/intro.md b/docs/docs/intro.md index dd77731d..0da07657 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -6,6 +6,21 @@ slug: / # Introduction -![Commit Boost Logo](/img/logo.jpg) +import CommitBoostLogo from '/img/logo.png'; +import Overview from '/img/overview.png'; -Due to the risks developing for Ethereum, core development, and its validators set, a group of teams / individuals are working on developing a public good called Commit-Boost. Commit-Boost is an open-source public good that is fully compatible with [MEV-Boost](https://github.com/flashbots/mev-boost), but acts as a light-weight validator platform to safely make commitments. Specifically, Commit-Boost is a new Ethereum validator sidecar focused on standardizing the last mile of communication between validators and third-party protocols. It's being developed in Rust from scratch, and has been designed with safety and modularity at its core, with the goal of not limiting the market downstream including stakeholders, flows, proposer commitments, enforcement mechanisms, etc. +Commit Boost Logo + +
+
+ +Commit-Boost is a new Ethereum validator sidecar focused on standardizing the communication between validators and third-party protocols. This open-source public good is fully compatible with [MEV-Boost](https://github.com/flashbots/mev-boost) and acts as a light-weight platform to allow validators to safely make commitments. + +Commit-Boost runs as a single sidecar composed of multiple modules: + +Commit Boost Overview + +
+
+ +Commit-Boost is being developed in Rust from scratch, and has been designed with safety and modularity at its core, with the goal of not limiting the market downstream including stakeholders, flows, proposer commitments, enforcement mechanisms, etc. diff --git a/docs/docs/overview.md b/docs/docs/overview.md index 7e821c50..5005bda8 100644 --- a/docs/docs/overview.md +++ b/docs/docs/overview.md @@ -5,31 +5,31 @@ sidebar_position: 2 # Overview ## Background -- Proposer commitments have been an important part of Ethereum’s history. Today, we already see the power of commitments where over 90% of validators give up their autonomy and make a wholesale commitment that outsources block building to a sophisticated actor called a block builder -- However, most are starting to agree on a common denominator: in the future, beacon proposers will face a broader set of options of what they may “commit" to–be it inclusions lists or preconfs or other types of commitments such as long-dated blockspace futures–compared to just an external or local payload they see today -- A recent post from Barnabe captures this well; during block construction, the validator “…creates the specs, or the template, by which the resulting block must be created, and the builders engaged by the proposer are tasked with delivering the block according to its specifications” -- While this all seems great, the challenge is that many teams building commitments are creating new sidecars driving fragmentation and risks for Ethereum -- For Ethereum, there are going to be significant challenges and increased risks during upgrades if there are a handful of sidecars validators are running -- For validators, these risks potentially take us to a world where proposers will need to make decisions on which teams to “bet on” and which sidecars they will need to run to participate in what those teams are offering -- For homestakers, this is difficult and they likely will be unable to participate in more than one of these commitments -- For sophisticated actors, this increases the attack vector and operational complexity as more and more sidecars are required to be run -- Another side effect of this is validators are somewhat locked into using a specific sidecar due to limited operational capacity and the switching costs of running a different sidecar (i.e., vendor lock-in). The higher the switching costs, the more embedded network effects could become if these sidecars only support certain downstream actors / proposer commitment protocols -- This also could create a dynamic where core out-of-protocol infrastructure supporting Ethereum which should be a public good, starts being used for monetization, distribution, or other purposes -- Commit-Boost aims to standardize how proposer commitment protocols communicate with the proposer, by providing a unified interface implemented in a single validator sidecar with the goal of reducing fragmentations +- Proposer commitments have been an important part of Ethereum’s history. Today, we already see the power of commitments where over 90% of validators give up their autonomy and make a wholesale commitment that outsources block building to a sophisticated actor called a block builder. +- However, most are starting to agree on a common denominator: in the future, beacon proposers will face a broader set of options of what they may “commit" to–be it inclusions lists or preconfs or other types of commitments such as long-dated blockspace futures–compared to just an external or local payload they see today. +- A recent post from Barnabe captures this well; during block construction, the validator “…creates the specs, or the template, by which the resulting block must be created, and the builders engaged by the proposer are tasked with delivering the block according to its specifications”. +- While this all seems great, the challenge is that many teams building commitments are creating new sidecars driving fragmentation and risks for Ethereum. +- For Ethereum, there are going to be significant challenges and increased risks during upgrades if there are a handful of sidecars validators are running. +- For validators, these risks potentially take us to a world where proposers will need to make decisions on which teams to “bet on” and which sidecars they will need to run to participate in what those teams are offering. +- For homestakers, this is difficult and they likely will be unable to participate in more than one of these commitments. +- For sophisticated actors, this increases the attack vector and operational complexity as more and more sidecars are required to be run. +- Another side effect of this is validators are somewhat locked into using a specific sidecar due to limited operational capacity and the switching costs of running a different sidecar (i.e., vendor lock-in). The higher the switching costs, the more embedded network effects could become if these sidecars only support certain downstream actors / proposer commitment protocols. +- This also could create a dynamic where core out-of-protocol infrastructure supporting Ethereum which should be a public good, starts being used for monetization, distribution, or other purposes. +- Commit-Boost aims to standardize how proposer commitment protocols communicate with the proposer, by providing a unified interface implemented in a single validator sidecar with the goal of reducing fragmentation. ## Goals -- Unify behind a software / standard to reduce fragmentation risks for Ethereum and its validators, while ensuring open innovation downstream from the proposer can flourish -- Create a neutral, open-source, public good for the safe development and distribution of proposer commitments protocols -- Provide a well-tested, reliable validator sidecar with support for advanced observability and telemetry +- Unify behind a software / standard to reduce fragmentation risks for Ethereum and its validators, while ensuring open innovation downstream from the proposer can flourish. +- Create a neutral, open-source, public good for the safe development and distribution of proposer commitments protocols. +- Provide a well-tested, reliable validator sidecar with support for advanced observability and telemetry. ## Why Commit-Boost? ### For validators -- Run a single sidecar with support for MEV-Boost and other proposer commitments protocols, such as preconfirmations and inclusion lists -- Out-of-the-box support for metrics reporting and dashboards to have clear insight into what is happening in your validator -- Plug-in system to add custom modules, e.g. receive a notification on Telegram if a relay fails to deliver a block +- Run a single sidecar with support for MEV-Boost and other proposer commitments protocols, such as preconfirmations and inclusion lists. +- Out-of-the-box support for metrics reporting and dashboards to have clear insight into what is happening in your validator. +- Plug-in system to add custom modules, e.g. receive a notification on Telegram if a relay fails to deliver a block. ### For developers -- A modular platform to develop and distribute proposer commitments protocols -- A single API to interact with validators -- Support for hard-forks and new protocol requirements +- A modular platform to develop and distribute proposer commitments protocols. +- A single API to interact with validators. +- Support for hard-forks and new protocol requirements. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index e1ad3486..f78ae69a 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -59,12 +59,12 @@ const config = { /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ // Replace with your project's social card - image: 'img/logo.jpg', + image: 'img/icon.png', navbar: { title: 'Commit Boost', logo: { - alt: 'Commit Boost Logo', - src: 'img/logo.jpg', + alt: 'Commit Boost Icon', + src: 'img/icon.png', }, items: [ { to: '/', label: 'Docs', position: 'left' }, @@ -111,6 +111,7 @@ const config = { prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula, + additionalLanguages: ['bash','toml'], }, }), }; diff --git a/docs/static/img/favicon.ico b/docs/static/img/favicon.ico index 402007d0..1c9f23b8 100644 Binary files a/docs/static/img/favicon.ico and b/docs/static/img/favicon.ico differ diff --git a/docs/static/img/icon.png b/docs/static/img/icon.png new file mode 100644 index 00000000..c2afc07b Binary files /dev/null and b/docs/static/img/icon.png differ diff --git a/docs/static/img/logo.jpg b/docs/static/img/logo.jpg deleted file mode 100644 index 1681c6a3..00000000 Binary files a/docs/static/img/logo.jpg and /dev/null differ diff --git a/docs/static/img/logo.png b/docs/static/img/logo.png new file mode 100644 index 00000000..c630a292 Binary files /dev/null and b/docs/static/img/logo.png differ diff --git a/docs/static/img/overview.png b/docs/static/img/overview.png new file mode 100644 index 00000000..9926e017 Binary files /dev/null and b/docs/static/img/overview.png differ