Feat/docs

docs/architecture-core-commit-boost.md

@@ -0,0 +1,6 @@
+# Core Commit-Boost
+Below is a schematic of Commit-Boost. This proposed architecture allows proposers to run one sidecar, but still retain the ability to opt into a network of proposer commitment modules. More specifically, with this middleware, the proposer will only need to (in the case of delegation) run one sidecar and limits their responsibilities to only selecting which module / proposer commitment protocol they would like to subscribe to.
+
+It is important to note that the below depiction contains just a few examples of proposer commitment modules that can run on Commit-Boost. The design space for modules is completely open / not gated by the Commit-Boost software. The Commit-Boost software also does not come with modules (these are developed by teams outside of the Commit-Boost software), proposers will be responsible for opting into the commitments they wish to subscribe to (i.e., a proposer is responsible for which modules they will subscribe to).
+![architecture](commit-boost.png)
+Using this as a middleware instead of direct modification to the consensus client or running a sidecar per commitment will allow for each component to be sustained independently and will provide for cross proposer commitment compatibility.

docs/architecture.md

@@ -0,0 +1,4 @@
+# Architecture
+The following are schematics and details around Commit-Boost.
+1. [Core Commit-Boost](architecture-core-commit-boost.md)
+2. [Terminology](terminology.md)

docs/background.md

@@ -0,0 +1,7 @@
+# Background
+- Proposer commitments have been an important part of Ethereum’s history and could continue to be a powerful unlock for Ethereum
+- Today, we already see the power of commitments where nearly 90% of validators currently make a wholesale commitment that outsources block building to a sophisticated actor called a block builder (facilitated by a software called MEV-Boost)
+- However, a wholesale commitment gives away the proposer’s autonomy over the block. Many are starting to realize that if proposers could make more granular commitments, there is a significant design space and opportunity for Ethereum and its validators
+- On the surface, all the efforts around proposer commitments are a unlock for Ethereum, with most starting to agree on a common denominator: in the future, validators will face a broader set of options of what they may “commit" to
+- While this all seems great, the challenge is that this already is and will continue to drive fragmentation and risks for Ethereum and proposers
+- Commit-Boost is aimed to standardize proposer commitment protocols communication with the proposer with unification behind one sidecar helping to reduce the risk of fragmentation

docs/communicating-with-signer.md

@@ -0,0 +1,53 @@
+# Communicating with the Signer Module
+The core of any commitment module is its interaction with the signer API. 
+Note:  Below examples will show snippets in Rust, however any language that allows for instantiation of an http client will work.
+Note: A more complete example of the Signer Module usage can be found here
+## Authentication 
+Communication between the proposer commitment module and Commit-Boost is authenticated with a JWT token. This token will be provided as `CB_JWT_<MODULE_NAME>` by the Commit-Boost launcher at initialization time.
+To discover which pubkeys a commitment can be made for call `/signer/v1/get_pubkeys`:
+```use serde::Deserialize;
+
+#[derive(Deserialize)]
+pub struct GetPubkeysResponse {
+    pub consensus: Vec<BlsPublicKey>,
+    pub proxy: Vec<BlsPublicKey>,
+}
+
+let url = format!("{}/signer/v1/get_pubkeys", COMMIT_BOOST_HOST);
+
+let pubkeys = reqwest::get(url)
+    .await
+    .unwrap()
+    .json::<GetPubkeysResponse>()
+    .unwrap()
+    .consensus;```
+Once you'd like to receive a signature to create a commitment, you'd create the request like so:
+```use serde_json::json;
+use alloy_rpc_types_beacon::BlsSignature
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SignRequest {
+    pub id: String,
+    pub pubkey: BlsPublicKey,
+    pub is_proxy: bool,
+    pub object_root: [u8; 32],
+}
+
+let sign_request_body = json!({
+	    "id": "0",
+	    "pubkey": "0xa02ccf2b03d2ec87f4b2b2d0335cf010bf41b1be29ee1659e0f0aca4d167db7e2ca1bf1d15ce12c1fac5a60901fd41db",
+	    "is_proxy": false,
+	    "object_root": "your32commitmentbyteshere0000000"
+	});
+
+let url = format!("{}/signer/v1/request_signature", COMMIT_BOOST_HOST);
+let client = reqwest::Client::new();
+let res = client
+	.post(url)
+	.json(sign_request_body)
+	.send()
+	.await
+	.unwrap();
+
+let signature_bytes = res.bytes().await.unwrap();
+let signature = BlsSignature::from_slice(&signature_bytes);```

docs/custom-module.md

@@ -0,0 +1,3 @@
+1. [Setting up a lean custom module in Rust](setup-module.md)
+1. [Set up metrics reporting in custom module](metrics-reporting.md)
+2. [Communicating with the Signer Module](communicating-with-signer.md)

docs/dist/index.css

@@ -0,0 +1,16 @@
+html {
+    box-sizing: border-box;
+    overflow: -moz-scrollbars-vertical;
+    overflow-y: scroll;
+}
+
+*,
+*:before,
+*:after {
+    box-sizing: inherit;
+}
+
+body {
+    margin: 0;
+    background: #fafafa;
+}

docs/dist/index.html

@@ -0,0 +1,19 @@
+<!-- HTML for static distribution bundle build -->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>Swagger UI</title>
+    <link rel="stylesheet" type="text/css" href="./swagger-ui.css" />
+    <link rel="stylesheet" type="text/css" href="index.css" />
+    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
+    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
+  </head>
+
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="./swagger-ui-bundle.js" charset="UTF-8"> </script>
+    <script src="./swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
+    <script src="./swagger-initializer.js" charset="UTF-8"> </script>
+  </body>
+</html>

docs/dist/oauth2-redirect.html

@@ -0,0 +1,79 @@
+<!doctype html>
+<html lang="en-US">
+<head>
+    <title>Swagger UI: OAuth2 Redirect</title>
+</head>
+<body>
+<script>
+    'use strict';
+    function run () {
+        var oauth2 = window.opener.swaggerUIRedirectOauth2;
+        var sentState = oauth2.state;
+        var redirectUrl = oauth2.redirectUrl;
+        var isValid, qp, arr;
+
+        if (/code|token|error/.test(window.location.hash)) {
+            qp = window.location.hash.substring(1).replace('?', '&');
+        } else {
+            qp = location.search.substring(1);
+        }
+
+        arr = qp.split("&");
+        arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';});
+        qp = qp ? JSON.parse('{' + arr.join() + '}',
+                function (key, value) {
+                    return key === "" ? value : decodeURIComponent(value);
+                }
+        ) : {};
+
+        isValid = qp.state === sentState;
+
+        if ((
+          oauth2.auth.schema.get("flow") === "accessCode" ||
+          oauth2.auth.schema.get("flow") === "authorizationCode" ||
+          oauth2.auth.schema.get("flow") === "authorization_code"
+        ) && !oauth2.auth.code) {
+            if (!isValid) {
+                oauth2.errCb({
+                    authId: oauth2.auth.name,
+                    source: "auth",
+                    level: "warning",
+                    message: "Authorization may be unsafe, passed state was changed in server. The passed state wasn't returned from auth server."
+                });
+            }
+
+            if (qp.code) {
+                delete oauth2.state;
+                oauth2.auth.code = qp.code;
+                oauth2.callback({auth: oauth2.auth, redirectUrl: redirectUrl});
+            } else {
+                let oauthErrorMsg;
+                if (qp.error) {
+                    oauthErrorMsg = "["+qp.error+"]: " +
+                        (qp.error_description ? qp.error_description+ ". " : "no accessCode received from the server. ") +
+                        (qp.error_uri ? "More info: "+qp.error_uri : "");
+                }
+
+                oauth2.errCb({
+                    authId: oauth2.auth.name,
+                    source: "auth",
+                    level: "error",
+                    message: oauthErrorMsg || "[Authorization failed]: no accessCode received from the server."
+                });
+            }
+        } else {
+            oauth2.callback({auth: oauth2.auth, token: qp, isValid: isValid, redirectUrl: redirectUrl});
+        }
+        window.close();
+    }
+
+    if (document.readyState !== 'loading') {
+        run();
+    } else {
+        document.addEventListener('DOMContentLoaded', function () {
+            run();
+        });
+    }
+</script>
+</body>
+</html>

docs/dist/swagger-initializer.js

@@ -0,0 +1,20 @@
+window.onload = function() {
+  //<editor-fold desc="Changeable Configuration Block">
+
+  // the following lines will be replaced by docker/configurator, when it runs in a docker-container
+  window.ui = SwaggerUIBundle({
+    url: "./signer-api.yml",
+    dom_id: '#swagger-ui',
+    deepLinking: true,
+    presets: [
+      SwaggerUIBundle.presets.apis,
+      SwaggerUIStandalonePreset
+    ],
+    plugins: [
+      SwaggerUIBundle.plugins.DownloadUrl
+    ],
+    layout: "StandaloneLayout"
+  });
+
+  //</editor-fold>
+};

docs/index.md

@@ -0,0 +1,30 @@
+# Introduction
+![logo](logo.jpeg)
+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 enable safe commitments. Specifically, Commit-Boost is a new Ethereum validator sidecar focused on standardizing the last mile of communication between validators and commitments. It has been designed with modularity at its core, with the goal of not limiting the range of different proposer commitments protocols and the open design space around those protocols. 
+
+## Background
+- Proposer commitments have been an important part of Ethereum’s history and could continue to be a powerful unlock for Ethereum
+- Today, we already see the power of commitments where nearly 90% of validators currently make a wholesale commitment that outsources block building to a sophisticated actor called a block builder (facilitated by a software called MEV-Boost)
+- However, a wholesale commitment gives away the proposer’s autonomy over the block. Many are starting to realize that if proposers could make more granular commitments, there is a significant design space and opportunity for Ethereum and its validators
+- On the surface, all the efforts around proposer commitments are a unlock for Ethereum, with most starting to agree on a common denominator: in the future, validators will face a broader set of options of what they may “commit" to
+- While this all seems great, the challenge is that this already is and will continue to drive fragmentation and risks for Ethereum and proposers
+- Commit-Boost is aimed to standardize proposer commitment protocols communication with the proposer with unification behind one sidecar helping to reduce the risk of fragmentation
+
+## What is Commit-Boost?
+### From the perspective of the proposer:
+- The Commit-Boost client is a single sidecar that acts as a platform to interact with proper commitment protocols
+- Standardized way to provide a signature / opt into a commitment
+- Helps monitor key attributes around that signature
+- Creates constraints / condition sets and pass these constraints downstream
+- Get insight to telemetry around the commitment flow and validator box that can be seen through dashboards such as a - Grafana
+- Create bespoke process management logic to ensure safety when making commitments
+### From the perspective of the proposer commitment protocol / module creator:
+- Framework / standard request a to have a proposer make a commitment
+
+## Table of Contents
+
+1. [Introduction](introduction.md)
+2. [Running As a Node Operator](running-as-node-operator.md)
+3. [Developing a Custom Module](custom-module.md)
+4. [Reference](reference.md)
+5. [Acknowledgements](acknowledgements.md)

docs/introduction.md

@@ -0,0 +1,6 @@
+# Introduction
+
+- [Background](background.md)
+- [What is Commit-Boost?](what-is-cb.md)
+- [Architecture](architecture.md)
+- [Discussion Points / Roadmap](roadmap.md)

docs/metrics-reporting.md

@@ -0,0 +1,31 @@
+# Set up metrics reporting in custom module
+1. Add the following dependencies to your Cargo.toml
+```[dependencies]
+cb-metrics.workspace = true
+prometheus.workspace = true
+lazy_static.workspace = true```
+2. Import the necessary dependencies:
+```use cb_metrics::sdk::MetricsProvider;
+use lazy_static::lazy_static;
+use prometheus::{IntCounter, Registry};```
+3. Lazy load the prometheus registry and custom metric (for example a counter):
+```// You can define custom metrics and a custom registry for the business logic of your module. These
+// will be automatically scaped by the Prometheus server
+lazy_static! {
+    pub static ref MY_CUSTOM_REGISTRY: prometheus::Registry =
+        Registry::new_custom(Some("da_commit".to_string()), None).unwrap();
+    pub static ref SIG_RECEIVED_COUNTER: IntCounter =
+        IntCounter::new("signature_received", "successful signatures requests received").unwrap();
+}```
+4. Initialize the registry and run the Module's metrics reporting server in main:
+```#[tokio::main]
+async fn main() {
+    ... rest of code
+    // Remember to register all your metrics before starting the process
+    MY_CUSTOM_REGISTRY.register(Box::new(SIG_RECEIVED_COUNTER.clone())).unwrap();
+    // Spin up a server that exposes the /metrics endpoint to Prometheus
+    MetricsProvider::load_and_run(MY_CUSTOM_REGISTRY.clone());
+    ... rest of code
+}```
+To update the metric in your business logic simply run:
+```    SIG_RECEIVED_COUNTER.inc();```

docs/reference.md

@@ -0,0 +1,3 @@
+# Reference
+1. [Signer API](signer-api.html)
+3. [Terminology](terminology.md)

docs/roadmap.md

@@ -0,0 +1,12 @@
+# Discussion Points / Roadmap
+- Signer: Least explored area, right now Commit-Boost is built to leverage a proxy key of the validator but we are post ETH CC / this post hope to engage on how best to safely design this
+
+- Docker and Binary: right now we just have support for Docker to instantiate modules, but shortly after ETH CC we plan to expand this to support binary (i.e., both Docker and binary will be enabled allowing the proper to select its preferred approach given the set-up)
+
+- More detailed telemetry and logging: We have some standard metrics reporting already, but plan to continue to expand this based on feedback / development work from a few teams across the community
+
+- Support for additional key managers (web3signer, ERC-2335, keystores, proxy): Right now we just have support for remote key signers, but are expanding this post ETH CC alongside the broader R&D efforts for the signer
+
+- Post ETH CC we plan to Increase modularity for services, including in-process monitoring and extensive configurability by the validator
+
+- Support both BLS and ECDSA

docs/running-as-node-operator.md

@@ -0,0 +1,44 @@
+# Running as a Node Operator
+## Overview
+Commit Boost currently has a "container-centric" approach, i.e. services are mapped to containers which are spawned using docker-compose.
+
+There are currently two modules that are provided by the core Commit-Boost:
+- the Proposer-Builder Separation (PBS) module (implements the [BuilderAPI](https://ethereum.github.io/builder-specs/) for [MEV Boost](https://docs.flashbots.net/flashbots-mev-boost/architecture-overview/specifications))
+- the signer module (implements the [Signer API](https://github.com/Commit-Boost/commit-boost-client/blob/main/api/signer-api.yml))
+
+While in development you have to build them manually as Commit Boost will search for the images to run, eventually we'll provide images to pull from the Docker registry. You can do so by running [this script](https://github.com/Commit-Boost/commit-boost-client/blob/main/scripts/build_local_images.sh)
+Commit Boost also supports "Commit Modules", which are modules that leverage the Signer API to request signatures from the proposer. You can find an example [here](https://github.com/Commit-Boost/commit-boost-client/blob/main/examples/da_commit). Commit Modules also need to be built as docker images and specified in the config file. You can build the local example by running [this script](https://github.com/Commit-Boost/commit-boost-client/blob/main/scripts/build_local_module.sh).
+
+Note: because Commit Boost currently uses Docker underneath, if you require `sudo` to interact with Docker, you will need `sudo` to launch some Commit Boost commands.
+
+## Config
+The main config file is a .toml which specifies how modules should be built, and their configs. Full specifations are WIP. You can find an example here
+## Build
+You can compile the project using
+```cargo build --release```
+### Initialize 
+Use this command to setup the Docker Compose file that will be used to run the services. For example:
+```./target/release/commit-boost init --config config.example.toml```
+This will create three files:
+- `cb.docker-compose.yml` - used to start services
+- `.cb.env` - with local env variables to be loaded at runtime
+- `targets.json`  - used by prometheus to dynamically discover metrics servers
+### Build docker containers
+Firstly, ensure you have Docker Engine up and running and authenticate using:
+```docker login```
+Then give execute permissions to the `scripts/build_local_images.sh` and `scripts/build_local_modules.sh` files:
+```chmod +x scripts/build_local_modules.sh scripts/build_local_images.sh```
+Finally, run the scripts:
+```
+./scripts/build_local_modules.sh
+./scripts/build_local_iamges.sh
+```
+
+### Start
+Once the init is done, you can start Commit Boost with start. For example:
+```./target/release/commit-boost start --docker cb.docker-compose.yml --env .cb.env```
+### Stop
+```./target/release/commit-boost stop --docker cb.docker-compose.yml --env .cb.env```
+### Logs
+To listen for logs:
+```./target/release/commit-boost logs --docker cb.docker-compose.yml```