WIP: MD docs

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/index.md

@@ -6,5 +6,6 @@ Commit-Boost is a powerful tool for optimizing your commit workflow.
 
 1. [Introduction](introduction.md)
 2. [Running As a Node Operator](running-as-node-operator.md)
-2. [Developing a Custom Module](custom-module.md)
-3
+3. [Developing a Custom Module](custom-module.md)
+4. [Reference](reference.md)
+5. [Acknowledgements](acknowledgements.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.md)
+3. [Terminology](terminology.md)

docs/running-as-node-operator.md

@@ -7,13 +7,13 @@ There are currently two modules that are provided by the core Commit-Boost:
 - 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. 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).
+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
+## Build
 You can compile the project using
 ```cargo build --release```
 ### Initialize 
@@ -35,11 +35,10 @@ Finally, run the scripts:
 ```
 
 ### 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
+### Stop
 ```./target/release/commit-boost stop --docker cb.docker-compose.yml --env .cb.env```
-Logs
+### Logs
 To listen for logs:
 ```./target/release/commit-boost logs --docker cb.docker-compose.yml```

docs/setup-module.md

@@ -0,0 +1,55 @@
+# Setting up a lean custom module in Rust
+1. Currently `cb_*` crates are not uploaded to crates.io , so easiest way to get started is to clone the commit-boost-client repo and initialize a new module in the examples folder
+2. Initialize a new project using `cargo new <my_module_name>`
+3. The Cargo.toml needs to have the cb_* dependencies from the root project
+```[dependencies]
+cb-cli.workspace = true
+cb-common.workspace = true
+cb-pbs.workspace = true
+cb-crypto.workspace = true```
+4. Import the cb modules in your main.rs:
+```use cb_common::{
+    commit::request::SignRequest,
+    config::{load_module_config, StartModuleConfig},
+    utils::initialize_tracing_log,
+};
+use cb_metrics::sdk::MetricsProvider;```
+5. Declare the extra config you need to parse in a struct:
+```// Extra configurations parameters can be set here and will be automatically parsed from the
+// .config.toml file These parameters will be in the .extra field of the
+// StartModuleConfig<ExtraConfig> struct you get after calling
+// `load_module_config::<ExtraConfig>()`
+#[derive(Debug, Deserialize)]
+struct ExtraConfig {
+    sleep_secs: u64,
+}```
+
+6. Your main method needs to have the setup boilerplate code:
+```#[tokio::main]
+async fn main() {
+    initialize_tracing_log();
+
+    match load_module_config::<ExtraConfig>() {
+        Ok(config) => {
+            info!(
+                module_id = config.id,
+                sleep_secs = config.extra.sleep_secs,
+                "Starting module with custom data"
+            );
+
+            let service = DaCommitService { config };
+
+            if let Err(err) = service.run().await {
+                error!(?err, "Service failed");
+            }
+        }
+        Err(err) => {
+            error!(?err, "Failed to load module config");
+        }
+    }
+}```
+## Build docker container
+Firstly, ensure you have Docker Engine up and running and authenticate using:
+```docker login```
+Then give execute permissions to the `scripts/build_local_modules.sh` script:
+```chmod +x scripts/build_local_modules.sh```

docs/terminology.md

@@ -0,0 +1,9 @@
+- Proposer: entity with the right to propose the next block
+- Commitment: a constraint or condition that the proposer choses and agrees to via a signature
+- Proxy Keys: provides signature to commitment representing the proposer
+- Extensions: product features that are built extending vanilla MEV-boost
+- Key Manager: some proposers use key managers or remote signers as part of their proposer / validator duties
+- Consensus Client: for example, Lighthouse or Teku (see [here](https://ethereum.org/en/developers/docs/nodes-and-clients/) for more details)
+- Module: allows the proposer to make a commitment and includes some of the logic of the proposer commitment protocol
+- Signer Manager: helps modules get signatures for their commitments
+- System Manager: ties everything together, logging, metrics, etc.