From 8a237ff1a2992918803b7fd0c2caf007f542d9a9 Mon Sep 17 00:00:00 2001
From: Fraser Hutchison <190532+Fraser999@users.noreply.github.com>
Date: Fri, 27 Feb 2026 16:54:00 +0000
Subject: [PATCH 1/6] reduce log level for stale bundles

---
 src/config.rs           |  2 +-
 src/tasks/cache/task.rs | 17 +++++++++++++++--
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/src/config.rs b/src/config.rs
index 83156a24..756bfeff 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -266,7 +266,7 @@ impl BuilderConfig {
     }
 
     /// Get an oauth2 token for the builder, starting the authenticator if it
-    // is not already running.
+    /// is not already running.
     pub fn oauth_token(&self) -> SharedToken {
         static ONCE: std::sync::OnceLock<SharedToken> = std::sync::OnceLock::new();
 
diff --git a/src/tasks/cache/task.rs b/src/tasks/cache/task.rs
index 1f9de1a7..994880d1 100644
--- a/src/tasks/cache/task.rs
+++ b/src/tasks/cache/task.rs
@@ -6,7 +6,7 @@ use tokio::{
     sync::{mpsc, watch},
     task::JoinHandle,
 };
-use tracing::{debug, info};
+use tracing::{debug, info, trace};
 
 /// Cache task for the block builder.
 ///
@@ -34,6 +34,8 @@ impl CacheTask {
     }
 
     async fn task_future(mut self, cache: SimCache) {
+        let mut skipped_bundle_count: u64 = 0;
+
         loop {
             let mut basefee = 0;
             tokio::select! {
@@ -48,6 +50,11 @@ impl CacheTask {
                         let _guard = env.span().enter();
                         let sim_env = env.rollup_env();
 
+                        if skipped_bundle_count > 0 {
+                            debug!(skipped_bundle_count, "skipped stale bundles for previous block");
+                            skipped_bundle_count = 0;
+                        }
+
                         basefee = sim_env.basefee;
                         info!(
                             basefee,
@@ -68,7 +75,13 @@ impl CacheTask {
 
                     // Don't insert bundles for past blocks
                     if env_block > bundle_block {
-                        debug!(env.block = env_block, bundle.block = bundle_block, "skipping bundle insert");
+                        trace!(
+                            env.block = env_block,
+                            bundle.block = bundle_block,
+                            %bundle.id,
+                            "skipping bundle insert"
+                        );
+                        skipped_bundle_count += 1;
                         continue;
                     }
 

From ff62cb8cfceea1f3e3635d31dd7ee73cb3e60874 Mon Sep 17 00:00:00 2001
From: Fraser Hutchison <190532+Fraser999@users.noreply.github.com>
Date: Mon, 9 Mar 2026 22:46:30 +0000
Subject: [PATCH 2/6] add further metrics

---
 src/tasks/cache/bundle.rs |  8 +++++++-
 src/tasks/cache/task.rs   | 15 +++++++++++++--
 src/tasks/cache/tx.rs     |  5 +++++
 3 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/src/tasks/cache/bundle.rs b/src/tasks/cache/bundle.rs
index 38c56ff1..79050821 100644
--- a/src/tasks/cache/bundle.rs
+++ b/src/tasks/cache/bundle.rs
@@ -1,6 +1,9 @@
 //! Bundler service responsible for fetching bundles and sending them to the simulator.
 use crate::config::BuilderConfig;
-use init4_bin_base::perms::tx_cache::{BuilderTxCache, BuilderTxCacheError};
+use init4_bin_base::{
+    deps::metrics::{counter, histogram},
+    perms::tx_cache::{BuilderTxCache, BuilderTxCacheError},
+};
 use signet_tx_cache::{
     TxCacheError,
     types::{BundleKey, CachedBundle},
@@ -65,6 +68,7 @@ impl BundlePoller {
                     if matches!(&error, BuilderTxCacheError::TxCache(TxCacheError::NotOurSlot)) {
                         trace!("Not our slot to fetch bundles");
                     } else {
+                        counter!("signet.builder.cache.bundle_poll_errors").increment(1);
                         warn!(%error, "Failed to fetch bundles from tx-cache");
                     }
                     return Err(error);
@@ -79,6 +83,7 @@ impl BundlePoller {
         }
 
         trace!(count = all_bundles.len(), "fetched all bundles from tx-cache");
+        histogram!("signet.builder.cache.bundles_fetched").record(all_bundles.len() as f64);
         Ok(all_bundles)
     }
 
@@ -98,6 +103,7 @@ impl BundlePoller {
             // exit the span after the check.
             drop(_guard);
 
+            counter!("signet.builder.cache.bundle_poll_count").increment(1);
             if let Ok(bundles) = self.check_bundle_cache().instrument(span.clone()).await {
                 for bundle in bundles.into_iter() {
                     if let Err(err) = outbound.send(bundle) {
diff --git a/src/tasks/cache/task.rs b/src/tasks/cache/task.rs
index 994880d1..74a1cd6f 100644
--- a/src/tasks/cache/task.rs
+++ b/src/tasks/cache/task.rs
@@ -1,5 +1,6 @@
 use crate::tasks::env::SimEnv;
 use alloy::consensus::{TxEnvelope, transaction::SignerRecoverable};
+use init4_bin_base::deps::metrics::counter;
 use signet_sim::SimCache;
 use signet_tx_cache::types::CachedBundle;
 use tokio::{
@@ -64,6 +65,7 @@ impl CacheTask {
                         cache.clean(
                             sim_env.number.to(), sim_env.timestamp.to()
                         );
+                        counter!("signet.builder.cache.cache_cleans").increment(1);
                     }
                 }
                 Some(bundle) = self.bundles.recv() => {
@@ -81,6 +83,7 @@ impl CacheTask {
                             %bundle.id,
                             "skipping bundle insert"
                         );
+                        counter!("signet.builder.cache.bundles_skipped").increment(1);
                         skipped_bundle_count += 1;
                         continue;
                     }
@@ -88,14 +91,22 @@ impl CacheTask {
                     let res = cache.add_bundle(bundle.bundle, basefee);
                     // Skip bundles that fail to be added to the cache
                     if let Err(e) = res {
+                        counter!("signet.builder.cache.bundle_add_errors").increment(1);
                         debug!(?e, "Failed to add bundle to cache");
                         continue;
                     }
+                    counter!("signet.builder.cache.bundles_ingested").increment(1);
                 }
                 Some(txn) = self.txns.recv() => {
                     match txn.try_into_recovered() {
-                        Ok(recovered_tx) => cache.add_tx(recovered_tx, basefee),
-                        Err(_) => debug!("Failed to recover transaction signature"),
+                        Ok(recovered_tx) => {
+                            cache.add_tx(recovered_tx, basefee);
+                            counter!("signet.builder.cache.txs_ingested").increment(1);
+                        }
+                        Err(_) => {
+                            counter!("signet.builder.cache.tx_recover_failures").increment(1);
+                            debug!("Failed to recover transaction signature");
+                        }
                     }
                 }
             }
diff --git a/src/tasks/cache/tx.rs b/src/tasks/cache/tx.rs
index 29a792ac..8a1de34f 100644
--- a/src/tasks/cache/tx.rs
+++ b/src/tasks/cache/tx.rs
@@ -5,6 +5,7 @@ use alloy::{
     providers::Provider,
 };
 use futures_util::TryStreamExt;
+use init4_bin_base::deps::metrics::{counter, histogram};
 use signet_tx_cache::{TxCache, TxCacheError};
 use std::time::Duration;
 use tokio::{sync::mpsc, task::JoinHandle, time};
@@ -81,6 +82,7 @@ impl TxPoller {
             };
 
             if tx.nonce() < tx_count {
+                counter!("signet.builder.cache.tx_nonce_stale").increment(1);
                 span_debug!(span, %sender, tx_nonce = %tx.nonce(), ru_nonce = %tx_count, "Dropping transaction with stale nonce");
                 return;
             }
@@ -107,12 +109,15 @@ impl TxPoller {
                 break;
             }
 
+            counter!("signet.builder.cache.tx_poll_count").increment(1);
             if let Ok(transactions) =
                 self.check_tx_cache().instrument(span.clone()).await.inspect_err(|error| {
+                    counter!("signet.builder.cache.tx_poll_errors").increment(1);
                     debug!(%error, "Error fetching transactions");
                 })
             {
                 let _guard = span.entered();
+                histogram!("signet.builder.cache.txs_fetched").record(transactions.len() as f64);
                 trace!(count = transactions.len(), "found transactions");
                 for tx in transactions.into_iter() {
                     self.spawn_check_nonce(tx, outbound.clone());

From 292f0db7a5c038e04e380b19486819e67ec161e2 Mon Sep 17 00:00:00 2001
From: Fraser Hutchison <190532+Fraser999@users.noreply.github.com>
Date: Fri, 27 Feb 2026 18:11:16 +0000
Subject: [PATCH 3/6] lower error log level to warn

---
 src/tasks/submit/flashbots.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/tasks/submit/flashbots.rs b/src/tasks/submit/flashbots.rs
index 177d2c3d..019f8bff 100644
--- a/src/tasks/submit/flashbots.rs
+++ b/src/tasks/submit/flashbots.rs
@@ -224,7 +224,7 @@ impl FlashbotsTask {
 
                     if let Err(err) = pylon.post_blob_tx(block_tx).await {
                         counter!("signet.builder.pylon.submission_failures").increment(1);
-                        error!(%err, "pylon submission failed");
+                        warn!(%err, "pylon submission failed");
                         return;
                     }
 

From deab0bb828ced1ff68fa85773a41640104a89635 Mon Sep 17 00:00:00 2001
From: Fraser Hutchison <190532+Fraser999@users.noreply.github.com>
Date: Fri, 27 Feb 2026 18:35:17 +0000
Subject: [PATCH 4/6] include build info startup log line

---
 Cargo.lock     | 63 +++++++++++++++++++++++++++++++++-----------------
 Cargo.toml     |  1 +
 bin/builder.rs |  7 ++++++
 src/lib.rs     |  3 ++-
 4 files changed, 52 insertions(+), 22 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index c9f7f185..a673d4d2 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -126,9 +126,9 @@ dependencies = [
 
 [[package]]
 name = "alloy-chains"
-version = "0.2.30"
+version = "0.2.31"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "90f374d3c6d729268bbe2d0e0ff992bb97898b2df756691a62ee1d5f0506bc39"
+checksum = "6d9d22005bf31b018f31ef9ecadb5d2c39cf4f6acc8db0456f72c815f3d7f757"
 dependencies = [
  "alloy-primitives",
  "alloy-rlp",
@@ -1008,14 +1008,13 @@ dependencies = [
 
 [[package]]
 name = "alloy-trie"
-version = "0.9.4"
+version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4d7fd448ab0a017de542de1dcca7a58e7019fe0e7a34ed3f9543ebddf6aceffa"
+checksum = "3f14b5d9b2c2173980202c6ff470d96e7c5e202c65a9f67884ad565226df7fbb"
 dependencies = [
  "alloy-primitives",
  "alloy-rlp",
  "arbitrary",
- "arrayvec",
  "derive_arbitrary",
  "derive_more",
  "nybbles",
@@ -2426,6 +2425,7 @@ dependencies = [
  "backon",
  "eyre",
  "futures-util",
+ "git-version",
  "init4-bin-base",
  "openssl",
  "reqwest",
@@ -4186,6 +4186,26 @@ dependencies = [
  "polyval",
 ]
 
+[[package]]
+name = "git-version"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ad568aa3db0fcbc81f2f116137f263d7304f512a1209b35b85150d3ef88ad19"
+dependencies = [
+ "git-version-macro",
+]
+
+[[package]]
+name = "git-version-macro"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53010ccb100b96a67bc32c0175f0ed1426b31b655d562898e57325f81c023ac0"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "git2"
 version = "0.20.4"
@@ -4935,9 +4955,9 @@ dependencies = [
 
 [[package]]
 name = "init4-bin-base"
-version = "0.18.0-rc.10"
+version = "0.18.0-rc.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "68276e396fb82c74e041c90e8d7d1aec8dc4cf877e201a87dfd5a5a45cd31f38"
+checksum = "6f21074644ebc7b46d36979eefafa21d3fd518164199edbfb37ade7f9ad438fc"
 dependencies = [
  "alloy",
  "async-trait",
@@ -4945,6 +4965,7 @@ dependencies = [
  "aws-sdk-kms",
  "axum 0.8.8",
  "chrono",
+ "futures-util",
  "init4-from-env-derive",
  "metrics",
  "metrics-exporter-prometheus",
@@ -5422,9 +5443,9 @@ checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
 [[package]]
 name = "libc"
-version = "0.2.182"
+version = "0.2.183"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6800badb6cb2082ffd7b6a67e6125bb39f18782f793520caee8cb8846be06112"
+checksum = "b5b646652bf6661599e1da8901b3b9522896f01e736bad5f723fe7a3a27f899d"
 
 [[package]]
 name = "libgit2-sys"
@@ -6149,18 +6170,18 @@ dependencies = [
 
 [[package]]
 name = "objc2-core-foundation"
-version = "0.3.1"
+version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1c10c2894a6fed806ade6027bcd50662746363a9589d3ec9d9bef30a4e4bc166"
+checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
 dependencies = [
  "bitflags 2.11.0",
 ]
 
 [[package]]
 name = "objc2-io-kit"
-version = "0.3.1"
+version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "71c1c64d6120e51cd86033f67176b1cb66780c2efe34dec55176f77befd93c0a"
+checksum = "33fafba39597d6dc1fb709123dfa8289d39406734be322956a69f0931c73bb15"
 dependencies = [
  "libc",
  "objc2-core-foundation",
@@ -7042,9 +7063,9 @@ dependencies = [
 
 [[package]]
 name = "quinn-proto"
-version = "0.11.13"
+version = "0.11.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f1906b49b0c3bc04b5fe5d86a77925ae6524a19b816ae38ce1e426255f1d8a31"
+checksum = "434b42fec591c96ef50e21e886936e66d3cc3f737104fdb9b737c40ffb94c098"
 dependencies = [
  "bytes",
  "getrandom 0.3.4",
@@ -11397,9 +11418,9 @@ dependencies = [
 
 [[package]]
 name = "sysinfo"
-version = "0.38.3"
+version = "0.38.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d03c61d2a49c649a15c407338afe7accafde9dac869995dccb73e5f7ef7d9034"
+checksum = "92ab6a2f8bfe508deb3c6406578252e491d299cbbf3bc0529ecc3313aee4a52f"
 dependencies = [
  "libc",
  "memchr",
@@ -13295,18 +13316,18 @@ dependencies = [
 
 [[package]]
 name = "zerocopy"
-version = "0.8.40"
+version = "0.8.42"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a789c6e490b576db9f7e6b6d661bcc9799f7c0ac8352f56ea20193b2681532e5"
+checksum = "f2578b716f8a7a858b7f02d5bd870c14bf4ddbbcf3a4c05414ba6503640505e3"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.40"
+version = "0.8.42"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f65c489a7071a749c849713807783f70672b28094011623e200cb86dcb835953"
+checksum = "7e6cc098ea4d3bd6246687de65af3f920c430e236bee1e3bf2e441463f08a02f"
 dependencies = [
  "proc-macro2",
  "quote",
diff --git a/Cargo.toml b/Cargo.toml
index ac37b498..c3280f0a 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -50,6 +50,7 @@ axum = "0.7.5"
 backon = { version = "1.6.0", features = ["tokio-sleep"] }
 eyre = "0.6.12"
 futures-util = "0.3.31"
+git-version = "0.3.9"
 openssl = { version = "0.10", features = ["vendored"] }
 reqwest = { version = "0.12.22", features = ["blocking", "json"] }
 thiserror = "2.0.17"
diff --git a/bin/builder.rs b/bin/builder.rs
index 1d41c6e8..a0d62b97 100644
--- a/bin/builder.rs
+++ b/bin/builder.rs
@@ -7,9 +7,14 @@ use builder::{
         submit::FlashbotsTask,
     },
 };
+use git_version::git_version;
 use init4_bin_base::deps::tracing::{info, info_span};
 use tokio::select;
 
+const GIT_COMMIT: &str =
+    git_version!(args = ["--always", "--match=", "--abbrev=7"], fallback = "unknown");
+const PKG_VERSION: &str = env!("CARGO_PKG_VERSION");
+
 // Note: Must be set to `multi_thread` to support async tasks.
 // See: https://docs.rs/tokio/latest/tokio/attr.main.html
 #[tokio::main(flavor = "multi_thread")]
@@ -17,6 +22,8 @@ async fn main() -> eyre::Result<()> {
     let _guard = init4_bin_base::init4();
     let init_span_guard = info_span!("builder initialization").entered();
 
+    info!(pkg_version = PKG_VERSION, git_commit = GIT_COMMIT, "starting builder");
+
     builder::config_from_env();
 
     // Pre-load the KZG settings in a separate thread.
diff --git a/src/lib.rs b/src/lib.rs
index fbe02fbc..071bf204 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -35,7 +35,8 @@ pub mod utils;
 pub mod test_utils;
 
 use init4_bin_base::utils::from_env::FromEnv;
-// Anonymous import suppresses warnings about unused imports.
+// Anonymous imports suppress warnings about unused crate dependencies.
+use git_version as _;
 use openssl as _;
 use signet_constants::SignetSystemConstants;
 use std::sync::OnceLock;

From 44146b77216c552c7233c63079caad0bb4be37a2 Mon Sep 17 00:00:00 2001
From: Fraser Hutchison <190532+Fraser999@users.noreply.github.com>
Date: Sat, 28 Feb 2026 02:23:17 +0000
Subject: [PATCH 5/6] improve startup output and provide help command line arg

---
 Cargo.lock                    | 11 +++---
 Cargo.toml                    |  5 +--
 bin/builder.rs                | 45 +++++++++++++++++++++---
 src/config.rs                 | 66 ++++++++++++++++++++++++++---------
 src/tasks/block/sim.rs        |  2 +-
 src/tasks/submit/flashbots.rs |  2 +-
 src/test_utils.rs             | 15 +++++---
 7 files changed, 111 insertions(+), 35 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index a673d4d2..9439afdd 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2427,6 +2427,7 @@ dependencies = [
  "futures-util",
  "git-version",
  "init4-bin-base",
+ "itertools 0.14.0",
  "openssl",
  "reqwest",
  "reth-chainspec",
@@ -4955,9 +4956,8 @@ dependencies = [
 
 [[package]]
 name = "init4-bin-base"
-version = "0.18.0-rc.11"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6f21074644ebc7b46d36979eefafa21d3fd518164199edbfb37ade7f9ad438fc"
+version = "0.18.0-rc.10"
+source = "git+https://github.com/init4tech/bin-base?branch=fraser%2Feng-1943%2Fvarious-updates#b9f9cad61b199ff278ffc4c6e9dbc348252de392"
 dependencies = [
  "alloy",
  "async-trait",
@@ -4965,7 +4965,7 @@ dependencies = [
  "aws-sdk-kms",
  "axum 0.8.8",
  "chrono",
- "futures-util",
+ "eyre",
  "init4-from-env-derive",
  "metrics",
  "metrics-exporter-prometheus",
@@ -4993,8 +4993,7 @@ dependencies = [
 [[package]]
 name = "init4-from-env-derive"
 version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b9c78527fcfeaecc9805e5736a7592a26ecad3b7845eb273c8c1710de0dbb0c"
+source = "git+https://github.com/init4tech/bin-base?branch=fraser%2Feng-1943%2Fvarious-updates#b9f9cad61b199ff278ffc4c6e9dbc348252de392"
 dependencies = [
  "proc-macro2",
  "quote",
diff --git a/Cargo.toml b/Cargo.toml
index c3280f0a..b9816dcc 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -51,6 +51,7 @@ backon = { version = "1.6.0", features = ["tokio-sleep"] }
 eyre = "0.6.12"
 futures-util = "0.3.31"
 git-version = "0.3.9"
+itertools = "0.14.0"
 openssl = { version = "0.10", features = ["vendored"] }
 reqwest = { version = "0.12.22", features = ["blocking", "json"] }
 thiserror = "2.0.17"
@@ -64,7 +65,7 @@ alloy-hardforks = "0.4.0"
 alloy-chains = "0.2"
 
 # comment / uncomment for local dev
-# [patch.crates-io]
+[patch.crates-io]
 # signet-constants = { path = "../signet-sdk/crates/constants" }
 # signet-types = { path = "../signet-sdk/crates/types" }
 # signet-zenith = { path = "../signet-sdk/crates/zenith" }
@@ -74,4 +75,4 @@ alloy-chains = "0.2"
 # signet-journal = { path = "../signet-sdk/crates/journal" }
 # signet-tx-cache = { path = "../signet-sdk/crates/tx-cache" }
 # signet-bundle = { path = "../signet-sdk/crates/bundle" }
-# init4-bin-base = { path = "../bin-base" }
+init4-bin-base = { git = "https://github.com/init4tech/bin-base", branch = "fraser/eng-1943/various-updates" }
diff --git a/bin/builder.rs b/bin/builder.rs
index a0d62b97..ebd51011 100644
--- a/bin/builder.rs
+++ b/bin/builder.rs
@@ -1,31 +1,68 @@
 #![recursion_limit = "256"]
 
 use builder::{
+    config::{BuilderConfig, env_var_info},
     service::serve_builder,
     tasks::{
         block::sim::SimulatorTask, cache::CacheTasks, env::EnvTask, metrics::MetricsTask,
         submit::FlashbotsTask,
     },
 };
+use eyre::bail;
 use git_version::git_version;
-use init4_bin_base::deps::tracing::{info, info_span};
+use init4_bin_base::{
+    deps::tracing::{info, info_span},
+    utils::from_env::FromEnv,
+};
 use tokio::select;
 
 const GIT_COMMIT: &str =
     git_version!(args = ["--always", "--match=", "--abbrev=7"], fallback = "unknown");
 const PKG_VERSION: &str = env!("CARGO_PKG_VERSION");
 
+fn should_print_help() -> bool {
+    std::env::args().any(|arg| {
+        let lowercase_arg = arg.to_ascii_lowercase();
+        lowercase_arg == "-h" || lowercase_arg == "--help"
+    })
+}
+
+fn print_help() {
+    let version = env!("CARGO_PKG_VERSION");
+    let env_vars = env_var_info();
+    println!(
+        r#"Signet block builder v{version}
+
+Run with no args. Configuration is via the following environment variables:
+{env_vars}
+"#
+    )
+}
+
 // Note: Must be set to `multi_thread` to support async tasks.
 // See: https://docs.rs/tokio/latest/tokio/attr.main.html
 #[tokio::main(flavor = "multi_thread")]
 async fn main() -> eyre::Result<()> {
-    let _guard = init4_bin_base::init4();
+    if should_print_help() {
+        print_help();
+        return Ok(());
+    }
+
+    if let Err(e) = BuilderConfig::check_inventory() {
+        for item in e {
+            eprintln!("missing environment variable: {}: {}", item.var, item.description);
+        }
+        bail!(
+            "missing at least one required environment variable; run with '--help' to see the list"
+        );
+    }
+
+    let config = builder::config_from_env();
+    let _guard = init4_bin_base::init(config.tracing.clone(), config.metrics);
     let init_span_guard = info_span!("builder initialization").entered();
 
     info!(pkg_version = PKG_VERSION, git_commit = GIT_COMMIT, "starting builder");
 
-    builder::config_from_env();
-
     // Pre-load the KZG settings in a separate thread.
     //
     // This takes ~3 seconds, and we want to do it in parallel with the rest of
diff --git a/src/config.rs b/src/config.rs
index 756bfeff..ff68cb53 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -3,7 +3,7 @@ use alloy::{
     network::{Ethereum, EthereumWallet},
     primitives::Address,
     providers::{
-        self, Identity, ProviderBuilder, RootProvider,
+        Identity, ProviderBuilder, RootProvider,
         fillers::{
             BlobGasFiller, ChainIdFiller, FillProvider, GasFiller, JoinFill, NonceFiller,
             SimpleNonceManager, WalletFiller,
@@ -15,11 +15,14 @@ use init4_bin_base::{
     perms::{Authenticator, OAuthConfig, SharedToken, pylon},
     utils::{
         calc::SlotCalculator,
-        from_env::FromEnv,
+        from_env::{EnvItemInfo, FromEnv, OptionalU8WithDefault, OptionalU64WithDefault},
+        metrics::MetricsConfig,
         provider::{ProviderConfig, PubSubConfig},
         signer::LocalOrAws,
+        tracing::TracingConfig,
     },
 };
+use itertools::Itertools;
 use signet_constants::SignetSystemConstants;
 use signet_zenith::Zenith;
 use std::borrow::Cow;
@@ -58,7 +61,7 @@ pub type FlashbotsProvider = FillProvider<
         >,
         WalletFiller<EthereumWallet>,
     >,
-    providers::RootProvider,
+    RootProvider,
 >;
 
 /// The default concurrency limit for the builder if the system call
@@ -145,7 +148,8 @@ pub struct BuilderConfig {
     /// The max number of simultaneous block simulations to run.
     #[from_env(
         var = "CONCURRENCY_LIMIT",
-        desc = "The max number of simultaneous block simulations to run"
+        desc = "The max number of simultaneous block simulations to run [default: std::thread::available_parallelism]",
+        optional
     )]
     pub concurrency_limit: Option<usize>,
 
@@ -153,27 +157,27 @@ pub struct BuilderConfig {
     /// Defaults to 80% (80) if not set.
     #[from_env(
         var = "MAX_HOST_GAS_COEFFICIENT",
-        desc = "Optional maximum host gas coefficient, as a percentage, to use when building blocks",
-        default = 80
+        desc = "Optional maximum host gas coefficient, as a percentage, to use when building blocks [default: 80]",
+        optional
     )]
-    pub max_host_gas_coefficient: Option<u8>,
+    pub max_host_gas_coefficient: OptionalU8WithDefault<80>,
 
     /// Number of milliseconds before the end of the slot to stop querying for new blocks and start the block signing and submission process.
     #[from_env(
         var = "BLOCK_QUERY_CUTOFF_BUFFER",
-        desc = "Number of milliseconds before the end of the slot to stop querying for new transactions and start the block signing and submission process. Quincey will stop accepting signature requests 2000ms before the end of the slot, so this buffer should be no less than 2000ms to match.",
-        default = 3000
+        desc = "Number of milliseconds before the end of the slot to stop querying for new transactions and start the block signing and submission process. Quincey will stop accepting signature requests 2000ms before the end of the slot, so this buffer should be no less than 2000ms to match. [default: 3000]",
+        optional
     )]
-    pub block_query_cutoff_buffer: u64,
+    pub block_query_cutoff_buffer: OptionalU64WithDefault<3000>,
 
     /// Number of milliseconds before the end of the slot by which bundle submission to Flashbots must complete.
     /// If submission completes after this deadline, a warning is logged.
     #[from_env(
         var = "SUBMIT_DEADLINE_BUFFER",
-        desc = "Number of milliseconds before the end of the slot by which bundle submission must complete. Submissions that miss this deadline will be logged as warnings.",
-        default = 500
+        desc = "Number of milliseconds before the end of the slot by which bundle submission must complete. Submissions that miss this deadline will be logged as warnings. [default: 500]",
+        optional
     )]
-    pub submit_deadline_buffer: u64,
+    pub submit_deadline_buffer: OptionalU64WithDefault<500>,
 
     /// The slot calculator for the builder.
     pub slot_calculator: SlotCalculator,
@@ -184,6 +188,12 @@ pub struct BuilderConfig {
     /// URL for the Pylon blob server API.
     #[from_env(var = "PYLON_URL", desc = "URL for the Pylon blob server API")]
     pub pylon_url: url::Url,
+
+    /// Tracing and OTEL configuration.
+    pub tracing: TracingConfig,
+
+    /// Metrics configuration.
+    pub metrics: MetricsConfig,
 }
 
 impl BuilderConfig {
@@ -311,10 +321,9 @@ impl BuilderConfig {
     }
 
     /// Returns the maximum host gas to use for block building based on the configured max host gas coefficient.
-    pub fn max_host_gas(&self, gas_limit: u64) -> u64 {
+    pub const fn max_host_gas(&self, gas_limit: u64) -> u64 {
         // Set max host gas to a percentage of the host block gas limit
-        ((gas_limit as u128 * (self.max_host_gas_coefficient.unwrap_or(80) as u128)) / 100u128)
-            as u64
+        ((gas_limit as u128 * self.max_host_gas_coefficient.into_inner() as u128) / 100u128) as u64
     }
 
     /// Connect to the Pylon blob server.
@@ -323,6 +332,31 @@ impl BuilderConfig {
     }
 }
 
+/// Get a list of the env vars used to configure the app.
+pub fn env_var_info() -> String {
+    // We need to remove the `SlotCalculator` env vars from the list. `SignetSystemConstants`
+    // already requires `CHAIN_NAME`, so we don't want to include `CHAIN_NAME` twice.  That also
+    // means the other `SlotCalculator` env vars are ignored since `CHAIN_NAME` must be set.
+    let is_not_from_slot_calc = |env_item: &&EnvItemInfo| match env_item.var {
+        "CHAIN_NAME" if env_item.optional => false,
+        "START_TIMESTAMP" | "SLOT_OFFSET" | "SLOT_DURATION" => false,
+        _ => true,
+    };
+    let inventory_iter = BuilderConfig::inventory().into_iter().filter(is_not_from_slot_calc);
+    let max_width = inventory_iter.clone().map(|env_item| env_item.var.len()).max().unwrap_or(0);
+    inventory_iter
+        .map(|env_item| {
+            format!(
+                "  {:width$}  {}{}",
+                env_item.var,
+                env_item.description,
+                if env_item.optional { " [optional]" } else { "" },
+                width = max_width
+            )
+        })
+        .join("\n")
+}
+
 #[cfg(test)]
 mod tests {
     /// Tests that URL sanitization correctly handles trailing slashes for url.join() behavior.
diff --git a/src/tasks/block/sim.rs b/src/tasks/block/sim.rs
index 4b4eee4e..4fd32e91 100644
--- a/src/tasks/block/sim.rs
+++ b/src/tasks/block/sim.rs
@@ -261,7 +261,7 @@ impl SimulatorTask {
             self.slot_calculator().current_point_within_slot_ms().expect("host chain has started");
 
         let slot_duration = self.slot_calculator().slot_duration() * 1000; // convert to milliseconds
-        let query_cutoff_buffer = self.config.block_query_cutoff_buffer;
+        let query_cutoff_buffer = self.config.block_query_cutoff_buffer.into_inner();
 
         // To find the remaining slot time, subtract the timepoint from the slot duration.
         // Then subtract the block query cutoff buffer from the slot duration to account for
diff --git a/src/tasks/submit/flashbots.rs b/src/tasks/submit/flashbots.rs
index 019f8bff..d9a5d1bd 100644
--- a/src/tasks/submit/flashbots.rs
+++ b/src/tasks/submit/flashbots.rs
@@ -253,7 +253,7 @@ impl FlashbotsTask {
             slot_calculator.current_point_within_slot_ms().expect("host chain has started");
 
         let slot_duration = slot_calculator.slot_duration() * 1000; // convert to milliseconds
-        let submit_buffer = self.config.submit_deadline_buffer;
+        let submit_buffer = self.config.submit_deadline_buffer.into_inner();
 
         // To find the remaining slot time, subtract the timepoint from the slot duration.
         // Then subtract the submit deadline buffer to give us margin before slot ends.
diff --git a/src/test_utils.rs b/src/test_utils.rs
index 1512171e..b5716058 100644
--- a/src/test_utils.rs
+++ b/src/test_utils.rs
@@ -6,17 +6,20 @@ use alloy::{
     rpc::client::BuiltInConnectionString,
     signers::{SignerSync, local::PrivateKeySigner},
 };
+use core::str::FromStr;
 use eyre::Result;
 use init4_bin_base::{
     deps::tracing_subscriber::{
         EnvFilter, Layer, fmt, layer::SubscriberExt, registry, util::SubscriberInitExt,
     },
     perms::OAuthConfig,
-    utils::{calc::SlotCalculator, provider::ProviderConfig},
+    utils::{
+        calc::SlotCalculator, metrics::MetricsConfig, provider::ProviderConfig,
+        tracing::TracingConfig,
+    },
 };
 use signet_constants::SignetSystemConstants;
 use std::env;
-use std::str::FromStr;
 use trevm::revm::{context::BlockEnv, context_interface::block::BlobExcessGasAndPrice};
 
 /// Set up a block builder with test values
@@ -53,11 +56,13 @@ pub fn setup_test_config() -> &'static BuilderConfig {
                 1740681556, // pecorino start timestamp as sane default
                 0, 1,
             ),
-            block_query_cutoff_buffer: 3000,
-            submit_deadline_buffer: 500,
-            max_host_gas_coefficient: Some(80),
+            block_query_cutoff_buffer: Default::default(),
+            submit_deadline_buffer: Default::default(),
+            max_host_gas_coefficient: Default::default(),
             constants: SignetSystemConstants::parmigiana(),
             pylon_url: "http://localhost:8081".parse().unwrap(),
+            tracing: TracingConfig::default(),
+            metrics: MetricsConfig::default(),
         }
     })
 }

From b2a0e3937e04a1d8faa956d20c7e32b0f1856cfb Mon Sep 17 00:00:00 2001
From: Fraser Hutchison <190532+Fraser999@users.noreply.github.com>
Date: Fri, 6 Mar 2026 18:00:11 +0000
Subject: [PATCH 6/6] update to match changes in bin-base

---
 bin/builder.rs    |  3 +-
 src/config.rs     | 11 ++++++
 src/lib.rs        | 28 +++++++++------
 src/test_utils.rs | 86 +++++++++++++++++++++++++----------------------
 4 files changed, 74 insertions(+), 54 deletions(-)

diff --git a/bin/builder.rs b/bin/builder.rs
index ebd51011..8eefa4c9 100644
--- a/bin/builder.rs
+++ b/bin/builder.rs
@@ -58,7 +58,6 @@ async fn main() -> eyre::Result<()> {
     }
 
     let config = builder::config_from_env();
-    let _guard = init4_bin_base::init(config.tracing.clone(), config.metrics);
     let init_span_guard = info_span!("builder initialization").entered();
 
     info!(pkg_version = PKG_VERSION, git_commit = GIT_COMMIT, "starting builder");
@@ -89,7 +88,7 @@ async fn main() -> eyre::Result<()> {
     let build_jh = simulator_task.spawn_simulator_task(cache_system.sim_cache, submit_channel);
 
     // Start the healthcheck server
-    let server = serve_builder(([0, 0, 0, 0], builder::config().builder_port));
+    let server = serve_builder(([0, 0, 0, 0], config.builder_port));
 
     // We have finished initializing the builder, so we can drop the init span
     // guard.
diff --git a/src/config.rs b/src/config.rs
index ff68cb53..8d338f2f 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -12,6 +12,7 @@ use alloy::{
 };
 use eyre::Result;
 use init4_bin_base::{
+    Init4Config,
     perms::{Authenticator, OAuthConfig, SharedToken, pylon},
     utils::{
         calc::SlotCalculator,
@@ -196,6 +197,16 @@ pub struct BuilderConfig {
     pub metrics: MetricsConfig,
 }
 
+impl Init4Config for BuilderConfig {
+    fn tracing(&self) -> &TracingConfig {
+        &self.tracing
+    }
+
+    fn metrics(&self) -> &MetricsConfig {
+        &self.metrics
+    }
+}
+
 impl BuilderConfig {
     /// Sanitizes URL fields to ensure consistent behavior with `url.join()`.
     ///
diff --git a/src/lib.rs b/src/lib.rs
index 071bf204..dfb7245d 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -34,27 +34,33 @@ pub mod utils;
 /// Test utilitites
 pub mod test_utils;
 
-use init4_bin_base::utils::from_env::FromEnv;
 // Anonymous imports suppress warnings about unused crate dependencies.
 use git_version as _;
+use init4_bin_base::ConfigAndGuard;
 use openssl as _;
 use signet_constants::SignetSystemConstants;
 use std::sync::OnceLock;
 
-/// Global static configuration for the Builder binary.
-pub static CONFIG: OnceLock<config::BuilderConfig> = OnceLock::new();
+/// Global static configuration and OTLP guard for the Builder binary. The
+/// guard is kept alive for the lifetime of the process.
+static CONFIG_AND_GUARD: OnceLock<ConfigAndGuard<config::BuilderConfig>> = OnceLock::new();
 
-/// Load the Builder configuration from the environment and store it in the
-/// global static CONFIG variable. Returns a reference to the configuration.
+/// Load the Builder configuration from the environment, initialize tracing and
+/// metrics, and store the config in the global static. Returns a reference to
+/// the configuration.
 ///
 /// # Panics
 ///
-/// Panics if the configuration cannot be loaded from the environment AND no
-/// other configuration has been previously initialized.
+/// Panics if the configuration cannot be loaded from the environment.
 pub fn config_from_env() -> &'static config::BuilderConfig {
-    CONFIG.get_or_init(|| {
-        config::BuilderConfig::from_env().expect("Failed to load Builder config").sanitize()
-    })
+    &CONFIG_AND_GUARD
+        .get_or_init(|| {
+            let mut config_and_guard = init4_bin_base::init::<config::BuilderConfig>()
+                .expect("Failed to load Builder config");
+            config_and_guard.config = config_and_guard.config.sanitize();
+            config_and_guard
+        })
+        .config
 }
 
 /// Get a reference to the global Builder configuration.
@@ -63,7 +69,7 @@ pub fn config_from_env() -> &'static config::BuilderConfig {
 ///
 /// Panics if the configuration has not been initialized.
 pub fn config() -> &'static config::BuilderConfig {
-    CONFIG.get().expect("Builder config not initialized")
+    &CONFIG_AND_GUARD.get().expect("Builder config not initialized").config
 }
 
 /// Get a reference to the Signet system constants from the global Builder
diff --git a/src/test_utils.rs b/src/test_utils.rs
index b5716058..733d6e32 100644
--- a/src/test_utils.rs
+++ b/src/test_utils.rs
@@ -9,6 +9,7 @@ use alloy::{
 use core::str::FromStr;
 use eyre::Result;
 use init4_bin_base::{
+    ConfigAndGuard,
     deps::tracing_subscriber::{
         EnvFilter, Layer, fmt, layer::SubscriberExt, registry, util::SubscriberInitExt,
     },
@@ -24,47 +25,50 @@ use trevm::revm::{context::BlockEnv, context_interface::block::BlobExcessGasAndP
 
 /// Set up a block builder with test values
 pub fn setup_test_config() -> &'static BuilderConfig {
-    crate::CONFIG.get_or_init(|| {
-        BuilderConfig {
-            host_rpc: "ws://host-rpc.pecorino.signet.sh"
-                .parse::<BuiltInConnectionString>()
-                .map(ProviderConfig::new)
-                .unwrap(),
-            ru_rpc: "ws://rpc.pecorino.signet.sh"
-                .parse::<BuiltInConnectionString>()
-                .unwrap()
-                .try_into()
-                .unwrap(),
-            flashbots_endpoint: "https://relay-sepolia.flashbots.net:443".parse().unwrap(),
-            quincey_url: "http://localhost:8080".into(),
-            sequencer_key: None,
-            builder_key: env::var("SEPOLIA_ETH_PRIV_KEY")
-                .unwrap_or_else(|_| B256::repeat_byte(0x42).to_string()),
-            builder_port: 8080,
-            builder_rewards_address: Address::default(),
-            rollup_block_gas_limit: 3_000_000_000,
-            tx_pool_url: "http://localhost:9000/".parse().unwrap(),
-            oauth: OAuthConfig {
-                oauth_client_id: "some_client_id".into(),
-                oauth_client_secret: "some_client_secret".into(),
-                oauth_authenticate_url: "http://localhost:8080".parse().unwrap(),
-                oauth_token_url: "http://localhost:8080".parse().unwrap(),
-                oauth_token_refresh_interval: 300, // 5 minutes
-            },
-            concurrency_limit: None, // NB: Defaults to available parallelism
-            slot_calculator: SlotCalculator::new(
-                1740681556, // pecorino start timestamp as sane default
-                0, 1,
-            ),
-            block_query_cutoff_buffer: Default::default(),
-            submit_deadline_buffer: Default::default(),
-            max_host_gas_coefficient: Default::default(),
-            constants: SignetSystemConstants::parmigiana(),
-            pylon_url: "http://localhost:8081".parse().unwrap(),
-            tracing: TracingConfig::default(),
-            metrics: MetricsConfig::default(),
-        }
-    })
+    &crate::CONFIG_AND_GUARD
+        .get_or_init(|| {
+            let config = BuilderConfig {
+                host_rpc: "ws://host-rpc.pecorino.signet.sh"
+                    .parse::<BuiltInConnectionString>()
+                    .map(ProviderConfig::new)
+                    .unwrap(),
+                ru_rpc: "ws://rpc.pecorino.signet.sh"
+                    .parse::<BuiltInConnectionString>()
+                    .unwrap()
+                    .try_into()
+                    .unwrap(),
+                flashbots_endpoint: "https://relay-sepolia.flashbots.net:443".parse().unwrap(),
+                quincey_url: "http://localhost:8080".into(),
+                sequencer_key: None,
+                builder_key: env::var("SEPOLIA_ETH_PRIV_KEY")
+                    .unwrap_or_else(|_| B256::repeat_byte(0x42).to_string()),
+                builder_port: 8080,
+                builder_rewards_address: Address::default(),
+                rollup_block_gas_limit: 3_000_000_000,
+                tx_pool_url: "http://localhost:9000/".parse().unwrap(),
+                oauth: OAuthConfig {
+                    oauth_client_id: "some_client_id".into(),
+                    oauth_client_secret: "some_client_secret".into(),
+                    oauth_authenticate_url: "http://localhost:8080".parse().unwrap(),
+                    oauth_token_url: "http://localhost:8080".parse().unwrap(),
+                    oauth_token_refresh_interval: 300, // 5 minutes
+                },
+                concurrency_limit: None, // NB: Defaults to available parallelism
+                slot_calculator: SlotCalculator::new(
+                    1740681556, // pecorino start timestamp as sane default
+                    0, 1,
+                ),
+                block_query_cutoff_buffer: Default::default(),
+                submit_deadline_buffer: Default::default(),
+                max_host_gas_coefficient: Default::default(),
+                constants: SignetSystemConstants::parmigiana(),
+                pylon_url: "http://localhost:8081".parse().unwrap(),
+                tracing: TracingConfig::default(),
+                metrics: MetricsConfig::default(),
+            };
+            ConfigAndGuard { config, guard: None }
+        })
+        .config
 }
 
 /// Returns a new signed test transaction with the provided nonce, value, and mpfpg.
